Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  XPUYOPUYO (6)


xpuyopuyo - A tetris-like puzzle game for X11.

This manpage agrees with version 0.9.5 of xpuyopuyo.


Command Switches
Player Controls
Network Gameplay
Ai Gameplay
See Also



xpuyopuyo [options]

xpuyopuyo --help


Xpuyopuyo is a Tetris-like puzzle game where you strive to match up four ‘‘blobs’’ of the same color. Each match gives you points, and also dumps gray rocks on your opponent which are irritating and troublesome to get rid of. Multiple matches at one time score more points, and result in more rocks being dumped on the opponent (much to their dismay). First person to fill up their screen with puyopuyo blobs loses.

The game features an AI, and is capable of single-player, human-human play, human-AI gameplay, or AI-AI gameplay (demo mode). It will keep track of the total number of matches each player recieves, and the number of single-matches, double-matches, triple-matches, etc. as well.

We ported it overnight to Linux, so we could play whenever we felt like. The AI’s evolved more slowly; the original implementation took a week to develop. The current implementation is evolved using genetic algorithms; more documentation on this is available in the distribution. I always welcome new AI rules, or suggestions to improve the AI.

This version is modelled on several other versions we have seen around; the original (which I have not had the opportunity to play) is made by Compile,

I release this so others may enjoy it. If this game causes someone out their to flame/flunk out of college, then apologies but it’s the game’s fault, not mine :). Additional information, documentation is available in the distribution.


The idea is to match up colored blobs together. A match is any chain of 4 or more blobs of the same color, that are adjacent to each other (up, down, right, or left). The game gives you a playing piece with two colored blobs, which you can move around the playing field and rotate as it falls to the ground. In gameplay, it is similar to Tetris.

You get points for completing a match, and all blobs involved in the match will disappear. Larger matches (matches of more than 4 blobs) and multiple matches at the same time score much more points.

Also, if you are in a 2-player game, then several rocks will be dumped on your opponent when you complete a match. Rocks have no color; a chain of rocks does not complete a match. However, any rock adjacent to a match will be eliminated. Again, larger matches and multiple matches at the same time will cause more rocks to be dumped onto the opponent.

(The truly unfortunate may discover the indestructible rock or other forms of evil rocks. You are truly fortunate if you survive such an encounter.)

The game ends when you fill up your playing field. So try to keep the playing field as low as possible. See the options below for some of the features of the game you can enable.


Many of xpuyopuyo’s options may be configured by the command line. A summary and description of available options is below. Note, that some options might not be available, depending on how you built xpuyopuyo. To see a list of supported options, run xpuyopuyo --help. Options are processed in the order they are read; later options can clobber earlier options, so it’s good to make the difficulty option the first one.

General options:
-h, --help
  Display a summary of the options available.
  This is insanity, Max! Or what if it’s genius?
-1, --oneplayer
  Select one player game. No rocks in this version. Either player’s controls will work in this mode.
-2, --twoplayer
  Select two player game, human versus human. Player 1’s controls are on the keyboard, and player 2’s are in the numeric keypad (this may be configured, however).
-a, --aiplayer
  Select two player game, human versus computer. Either player’s controls will work for the human player.
-d, --demo
  Select two player game, computer versus computer. Fun to setup two different AI’s against each other and watch them go (the current longest running demo game I’ve seen was 57 hours long, and that was only ended by a bug in the timer code which caused one of the AI’s to pause. By the time I noticed what had happened, the other AI had racked up an unbelievable 6,000 rocks against his frozen opponent ...).
-e, --easy
  Easy gameplay. Enables options for easier gameplay. This option is currently equivalent to --noaidrop -number=4 --nullify --noindestructibles.
-m, --medium
  Medium gameplay. Enables more difficult round. Currently, this is equivalent to the following: --aidrop -number=5 --nullify --indestructibles.
-H, --hard
  Hard gameplay. Enables the most difficult of gameplay. Currently, this is equivalent to the following: --aidrop -number=6 --nonullify --indestructibles. Later options can override the options set by -e, -m, or -H.
-n, --number=n
  Specify the number of colors to use. This value can range from 4 to 6. The default is set by the difficulty level.
-t, --restart
  This is a toggle option. Automatically restart after a ‘‘Game Over’’. Useful when combined with the -d flag. The inversion of this flag is -/t, --norestart.
-T, --tutorial
  This is a toggle option. Enable tutorial mode. In tutorial mode, an AI will assist you by choosing a move it thinks is appropriate. You may still control the piece with the player controls. The inversion of this flag is -/T, --notutorial.
--theme name
  Select a theme to use on startup. The default is ‘‘default’’.
  This is a toggle option. When set, tooltips are displayed. The default is for this flag to be set. To turn off tooltips, use --notooltips.
  This is a toggle option. When set, no output is printed to stdout. The default is for this flag to be cleared. To turn off quiet use --noquiet.
Sound Options:
-S, --sound
  This is a toggle option that enables music and sound effects. The inversion of this flag is -/S, --nosound.
  This is a toggle option that enables use of the high quality mixer provided by mikmod. Depending on your soundcard, this may have no effect. Defaults to off, to turn off high quality mixing use --nohqmixer.
  This is a toggle option that enables sound effects. Defaults to on when sound is supported. To turn off sound effects use --noeffects.
Advanced Options:
  Specify the width of the playing field. The default is 6.
  Specify the height of the playing field. The default is 14.
  Specify the number of blobs in a chain required for a match. The default is 4. For more difficult gameplay, increase this value.
-U, --nullify
  This is a toggle option. When on, your rocks can nullify the opponents rocks. During the game, when you complete a match rocks are sent to the opponent, but they do not fall until their playing piece lands. In the meantime, if they accumulate any rocks against you, the rocks may instead be used to nullify the rocks accumulated against them. If this option is off, then all rocks that are sent will fall on the opponent -- eventually. This option is on in easier gameplay; the inversion of this flag is -/U, --nonullify.
-I, --indestructibles
  This is a toggle option. When on, "indestructible" blocks are allowed in the game. If a player accumulates a large number of matches at once (a quintuple-match is usually enough), then in addition to several rows of rocks being dumped on the opponent, an indestructible block will also fall on the opponent. This rock cannot be destroyed, and the best the opponent can do is try to get it down to the bottom of the screen where it is at least out of the way. This mode of gameplay can make life very interesting, indeed. This is only enabled by default on hard difficulty; the inverwsion of this flag is -/I, --noindestructibles.
Player Options:
-s, --speed=n
  Set the speed for falling blocks for the player, in milliseconds per drop. The default is determined by difficulty level. A typical value is 350.
-A, --accel=n
  Set the acceleration of the speed over time, in percentage of time lost per minute. This speeds the game up over time. An acceleration is only enabled on the harder difficulty levels. The acceleration is a floating-point value between 0 and 1.
AI Options:
-r, --airule2=n
  Select the AI rule for the right player. This option is better set in the user interface, under the AI menu. n must be an integer value. If n is random then a random AI is chosen.
-R, --airule1=n
  Select the AI rule for the left player. This option is better set in the user interface, under the AI menu. n must be an integer value. If n is random then a random AI is chosen.
-c, --aiscore
  This is a toggle option. This is a debug option, and is better left turned off. If set, the "AI score" is displayed instead of the next piece in the main game. The AI score is the ranking for the current move; higher scores mean the AI judged a particular move to be "better". Note that since each AI has its own ideas on what makes a good move, this score is highly dependent on the mindset of the selected AI. There’s not even any attempt to normalise the AI score with scores from its peers. So this number cannot be meaningfully compared with scores for other AI’s. The inversion of this option is -/c, --noaiscore.
-i, --aidrop
  This is a toggle option. If set, the AI is allowed to drop pieces when the human opponent drops a piece. This allows the AI to keep up with human players, and makes for a more challenging game. This option is on by default on higher difficulty levels; the inversion of this is -/i, --noaidrop.
Network Options:
  This starts a new server. The server has the advantage of being able to set the game options. It will wait for a connection from a client, then the game may begin. The server will listen on the default port unless --port is also given.
  This connects to the server specified. The connection will be made to the default port on the server given, unless the --port option is also given.
  This specifies an alternate port than the default, for network games.
  Enables AI in a network game. This is intended for debugging only. This is a toggle option; its inverse is --nonetworkai.
Tournament Options:

The tournament options are for AI breeding mode only, and are not well documented. They are: -z, --tournament, -Z, --hypertournament, and -Y

In the GTK version, there will be exactly one indestructible block in the About box. Curious, don’t you think?


The player controls are configurable in the game. They may be viewed and/or redefined in the Options menu. You can define up to three keys per action per player. The actions are left, right, rotate, and drop.

Note, that when you assign keys, key combinations are not allowed, and you should probably avoid attempting to assign a modifier key. The keys Enter, P, and Escape will restart the current game, pause a game, and end the current game (respectively) unless you assign these keys to a player control. If you assign these keys as player controls, you can still use Ctrl-R, Ctrl-Z, and Ctrl-P to perform the same actions.

When in single-player or human-AI mode, you may use either player’s controls to control your game field.


Network gameplay is much like normal 2-player gameplay, except you must first setup a network connection between two games. One xpuyopuyo game will act as a server, and the other will act as a client. First, on the server side, select the Network menu, Server and click Ok (you may change the port to listen to, if you like). Then on the client side, select the Network, Client Connection. Enter the machine name of the server and the port number to use (if you changed it in the server) and click Ok.

To begin a network game, both players must select New Game in the Game menu. The game will wait until both players are ready before starting the game.


AI’s are created using Genetic Algorithms. The flexible formulas allow the AI to take advantage of certain scenarios, and allow the AI to weight them accordingly. The rules are changing constantly as the AI evolves, and suggestions on new rules are welcome. A general list of strategies follows (not sorted in any particular order). The AI checks every possible move with the current piece and uses the rules it evolved to determine which is the best move.
Distance from top of playing field
  We don’t want the AI to stack up all its pieces at the top of the screen.
Hard limit to the height of structures
  As much as we don’t like height, we really don’t want the AI building things within the top four or so rows of the field. This rule carries a lot of weight in all AI personalities.
Opportunity to complete a match
Bonus to complete several matches at once
  The AI decides this by simulating what would happen if it put the game piece in various locations.
Penalty for blocking a potential match
  For example, covering a hole with three blobs of the same color already present). Some AI’s choose to break this rule more than others; in general these AI’s tend to get more multiple-matches (often triples or quadruples).
Eliminating rocks
  Some AI’s consider it a small benefit to try to eliminate as many rocks as possible. If the AI has a choice of two matches, the deciding factor could be in which one eliminates more rocks.


  A list of AI rules. To reset the AI rules to the defaults, remove these files.
  Configuration options for xpuyopuyo. All of these options can be set from the interface, there should be no need to edit this file directly.
  High scores for xpuyopuyo.
  User-defined keys for player controls.
  Manual page for xpuyopuyo. This is installed to your local share directory, and used for the on-line help system.
  Copy of the GPL. This is installed to your local share directory, and used for the on-line help system.


The xpuyopuyo home page at <>. There is also additional documentation in the distribution, under the doc/ directory.


xpuyopuyo was written by Justin David Smith <justins(at)>, and the original images were designed by Owen Aftreth. The first GTK version was ported by Havoc Pennington.

This manual page written by Justin David Smith <justins(at)>. Copyright(c) 2001,2000-1999 Justin David Smith.

(Please do not list these e-mail addresses on webpages, or list them in other packages, without contacting us first.)

Search for    or go to Top of page |  Section 6 |  Main Index

Justin David Smith XPUYOPUYO (6) March 2000

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.