Difference between revisions of "Command line parameters"

From Bitfighter
(Resolving the level folder)
(Options for hosting)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
Bitfighter can be started with a number of command line parameters. These will override the behavior and settings stored in the INI file.  Most players can ignore these most of the time.
 
Bitfighter can be started with a number of command line parameters. These will override the behavior and settings stored in the INI file.  Most players can ignore these most of the time.
  
=Player-oriented options=
+
=Player-oriented options=  
* '''-connect''' ''<address>'' Connect to server at specified address.
+
 
* '''-master''' ''<address>'' Use master server (game finder) at specified address
 
* '''-master''' ''<address>'' Use master server (game finder) at specified address
* '''-name''' ''<string>'' Specify your user name
+
* '''-name''' ''<string>'' Specify your username
* '''-usestick''' ''<int>'' Specify a joystick or other input device to use.  Default is 1.
+
* '''-password''' ''<string>'' Specify your password
 +
* '''-usestick''' ''<int>'' Specify which joystick or other input device to use.  Default is 1.
 
* '''-window''' Start in windowed mode
 
* '''-window''' Start in windowed mode
* '''-winpos''' ''<int> <int>''  Specify x,y location of game window (note that this is the position of the UL corner of the game canvas, and does not account for any window borders)
+
* '''-winpos''' ''<int> <int>''  Specify x,y location of game window (note that this is the position of the UL corner of the game canvas, and does not account for the window frame)
* '''-winwidth''' ''<int>''  Specify width of game window.  Height will be set automatically.  Note that the specified width is the width of the game canvas itself, and does not take account of window borders.
+
* '''-winwidth''' ''<int>''  Specify width of game window.  Height will be set automatically.  Note that the specified width is the width of the game canvas itself, and does not take account of window borders.  Therefore, the entire window width will exceed the size specified slightly.
* '''-fullscreen''' Start in full-screen mode
+
* '''-fullscreen''', '''-fullscreen-stretch''' Start in full-screen mode
 
* '''-rules''' Prints out a list of "rules of the game" and other possibly useful data
 
* '''-rules''' Prints out a list of "rules of the game" and other possibly useful data
* '''-help''' Print a brief help message and exit (might not work on Windows)
+
* '''-help''' Print a brief help message and exit
  
 
=Options for hosting=
 
=Options for hosting=
* '''-serverpassword''' ''<string>'' Specify a server password (if connecting to a private server)
+
* '''-serverpassword''' ''<string>'' Specify a server password (players will need to know this to connect to your server)
 
* '''-adminpassword''' ''<string>'' Specify an admin password (allowing those with the password to kick players and change their teams) when you host a game or run a dedicated server
 
* '''-adminpassword''' ''<string>'' Specify an admin password (allowing those with the password to kick players and change their teams) when you host a game or run a dedicated server
 
* '''-levelchangepassword''' ''<string>'' Specifies the password required for players to be able to change levels on your server when you host a game or run a dedicated server
 
* '''-levelchangepassword''' ''<string>'' Specifies the password required for players to be able to change levels on your server when you host a game or run a dedicated server
Line 20: Line 20:
 
* '''-hostdescr''' ''<string>'' Sets a brief description of the server, which will be visible when players browse for game servers.  Use double quotes (") for descriptions containing spaces.
 
* '''-hostdescr''' ''<string>'' Sets a brief description of the server, which will be visible when players browse for game servers.  Use double quotes (") for descriptions containing spaces.
 
* '''-maxplayers''' ''<int>'' Max players allowed in a game (default is 128)
 
* '''-maxplayers''' ''<int>'' Max players allowed in a game (default is 128)
* '''-server''' ''[address]'' Start game in server mode, and optionally bind to specified address.
 
 
* '''-dedicated''' ''[address]'' Run as a dedicated game server (i.e. no game window)
 
* '''-dedicated''' ''[address]'' Run as a dedicated game server (i.e. no game window)
  
Line 34: Line 33:
  
 
All of the following options can be specified with either a relative or absolute path.  They are primarily intended to make installation on certain Linux platforms more flexible; they are not meant for daily use by average users.
 
All of the following options can be specified with either a relative or absolute path.  They are primarily intended to make installation on certain Linux platforms more flexible; they are not meant for daily use by average users.
 +
* '''-cachedir''' ''<path>'' Folder where cache files are stored
 
* '''-inidir''' ''<path>'' Folder where INI file is stored
 
* '''-inidir''' ''<path>'' Folder where INI file is stored
 
* '''-logdir''' ''<path>'' Folder where logfiles will be written
 
* '''-logdir''' ''<path>'' Folder where logfiles will be written
* '''-luadir''' ''<path>'' Folder where Lua helper scripts are stored
+
* '''-scriptsdir''' ''<path>'' Folder where Lua helper scripts are stored
 
* '''-robotdir''' ''<path>'' Folder where robot scripts are stored
 
* '''-robotdir''' ''<path>'' Folder where robot scripts are stored
 
* '''-screenshotdir''' ''<path>'' Folder where screenshots are stored
 
* '''-screenshotdir''' ''<path>'' Folder where screenshots are stored
 
* '''-sfxdir''' ''<path>'' Folder where sounds are stored
 
* '''-sfxdir''' ''<path>'' Folder where sounds are stored
  
The easiest way to configure the major user data settings is with the rootDataDir setting.
+
The easiest way to configure the user data settings is with the rootDataDir setting.
 
* '''-rootDataDir''' ''<path>'' is equivalent to setting the -inidir, -logdir, -robotdir, -screenshotdir, and -leveldir parameters.  The application will automatially append "/robots", "/screenshots", and "/levels" to ''path'' as appropriate.
 
* '''-rootDataDir''' ''<path>'' is equivalent to setting the -inidir, -logdir, -robotdir, -screenshotdir, and -leveldir parameters.  The application will automatially append "/robots", "/screenshots", and "/levels" to ''path'' as appropriate.
  
Line 51: Line 51:
 
Here is a pseudo code version of how the various variables interact.  Working from top to bottom, the first item that produces the name of an existing folder will be used.
 
Here is a pseudo code version of how the various variables interact.  Working from top to bottom, the first item that produces the name of an existing folder will be used.
  
  ''rootDataDir'' is specified on the command line via the -rootdatadir parameter
+
  ''rootDataDir'' is specified on the command line via the -rootdatadir param
  ''levelDir''    is specified on the command line via the -leveldir parameter
+
  ''levelDir''    is specified on the command line via the -leveldir param
 
  ''iniLevelDir'' is specified in the INI file
 
  ''iniLevelDir'' is specified in the INI file
 
   
 
   
Line 81: Line 81:
 
* '''-lag''' ''<integer>'' Simulate the specified amount of server lag (in milliseconds)
 
* '''-lag''' ''<integer>'' Simulate the specified amount of server lag (in milliseconds)
 
* '''-jsave''' ''<string>'' Record a game to a journal for later playback. Specify where to save the game.  Useful for demonstrating and reporting bugs or other issues.
 
* '''-jsave''' ''<string>'' Record a game to a journal for later playback. Specify where to save the game.  Useful for demonstrating and reporting bugs or other issues.
* '''-jplay''' ''<string>'' Play back a journaled game. Specify the playback file name.
+
* '''-jplay''' ''<string>'' Play back a journaled game. Specify the playback file name.  ''May no longer work.''
 +
*'''-forceUpdate''' Tricks game into thinking it needs to update.
 +
 
 +
=Advanced server management options=
 +
* '''-sendres''' ''<server address>'' ''<admin password>'' ''<resource name>'' ''<level|levelgen|bot>'' - Send a resource to a remote server.  Address must be specified in the form IP:nnn.nnn.nnn.nnn:port.  The server must be running, have an admin password set, and have resource management enabled (in the [Host] section).
 +
* '''-getres''' ''<server address>'' ''<admin password>'' ''<resource name>'' ''<level|levelgen|bot>'' - Retrieves a resource from a remote server, using the same arguments as -sendres.
  
 
Notes:<br>
 
Notes:<br>

Latest revision as of 05:20, 11 February 2011

Bitfighter can be started with a number of command line parameters. These will override the behavior and settings stored in the INI file. Most players can ignore these most of the time.

Player-oriented options

  • -master <address> Use master server (game finder) at specified address
  • -name <string> Specify your username
  • -password <string> Specify your password
  • -usestick <int> Specify which joystick or other input device to use. Default is 1.
  • -window Start in windowed mode
  • -winpos <int> <int> Specify x,y location of game window (note that this is the position of the UL corner of the game canvas, and does not account for the window frame)
  • -winwidth <int> Specify width of game window. Height will be set automatically. Note that the specified width is the width of the game canvas itself, and does not take account of window borders. Therefore, the entire window width will exceed the size specified slightly.
  • -fullscreen, -fullscreen-stretch Start in full-screen mode
  • -rules Prints out a list of "rules of the game" and other possibly useful data
  • -help Print a brief help message and exit

Options for hosting

  • -serverpassword <string> Specify a server password (players will need to know this to connect to your server)
  • -adminpassword <string> Specify an admin password (allowing those with the password to kick players and change their teams) when you host a game or run a dedicated server
  • -levelchangepassword <string> Specifies the password required for players to be able to change levels on your server when you host a game or run a dedicated server
  • -hostname <string> Sets the name that will appear in the server browser when searching for servers
  • -hostdescr <string> Sets a brief description of the server, which will be visible when players browse for game servers. Use double quotes (") for descriptions containing spaces.
  • -maxplayers <int> Max players allowed in a game (default is 128)
  • -dedicated [address] Run as a dedicated game server (i.e. no game window)

Specifying levels

  • -levels <level 1> [level 2]... Note that all remaining items on the command line will be interpreted as levels, so this must be the last parameter.
  • -leveldir <folder or subfolder> Loads all levels in specified system folder, or a subfolder under the levels folder. Levels will be loaded in alphabetical order by level-file name. Admins can create custom level lists by copying selected levels into folders or subfolders, and rename the files to get them to load in the proper order.

Please see Hosting a game for more information about specifying levels.

Specifying folders

(Most of this section only applies to release 013 and above)

  • -leveldir <folder or subfolder> See previous section for details

All of the following options can be specified with either a relative or absolute path. They are primarily intended to make installation on certain Linux platforms more flexible; they are not meant for daily use by average users.

  • -cachedir <path> Folder where cache files are stored
  • -inidir <path> Folder where INI file is stored
  • -logdir <path> Folder where logfiles will be written
  • -scriptsdir <path> Folder where Lua helper scripts are stored
  • -robotdir <path> Folder where robot scripts are stored
  • -screenshotdir <path> Folder where screenshots are stored
  • -sfxdir <path> Folder where sounds are stored

The easiest way to configure the user data settings is with the rootDataDir setting.

  • -rootDataDir <path> is equivalent to setting the -inidir, -logdir, -robotdir, -screenshotdir, and -leveldir parameters. The application will automatially append "/robots", "/screenshots", and "/levels" to path as appropriate.

If you set both -rootDataDir and, say, -inidir, the value specified with -inidir will take precedence.

Resolving the level folder

Actually resolving the level folder can get fairly complex. Generally, we prioritize things specified on the command line over those set in the INI file, and, generally, we prefer specific settings (-leveldir) over more general ones (-rootdatadir).

Here is a pseudo code version of how the various variables interact. Working from top to bottom, the first item that produces the name of an existing folder will be used.

rootDataDir is specified on the command line via the -rootdatadir param
levelDir    is specified on the command line via the -leveldir param
iniLevelDir is specified in the INI file


If rootDataDir is specified then
    If levelDir is also specified
       levelDir       ==> will have the effect of ignoring rootDataDir
       rootDataDir/levels/levelDir
       rootDataDir/levelDir 
    End
	
    rootDataDir/levels
End	   ==> Don't use rootDataDir
     
If iniLevelDir is specified
   If levelDir is also specified try
       iniLevelDir/levelDir
   End	
   iniLevelDir
End	 ==> Don't use iniLevelDir
     
levels  ==> subfolder of "current" folder

If none of the above exist, you will be unable to host a game or edit levels.

Developer-oriented options

  • -loss <float> Simulate the specified amount of packet loss, from 0 (no loss) to 1 (all packets lost) [I think range is correct...]
  • -lag <integer> Simulate the specified amount of server lag (in milliseconds)
  • -jsave <string> Record a game to a journal for later playback. Specify where to save the game. Useful for demonstrating and reporting bugs or other issues.
  • -jplay <string> Play back a journaled game. Specify the playback file name. May no longer work.
  • -forceUpdate Tricks game into thinking it needs to update.

Advanced server management options

  • -sendres <server address> <admin password> <resource name> <level|levelgen|bot> - Send a resource to a remote server. Address must be specified in the form IP:nnn.nnn.nnn.nnn:port. The server must be running, have an admin password set, and have resource management enabled (in the [Host] section).
  • -getres <server address> <admin password> <resource name> <level|levelgen|bot> - Retrieves a resource from a remote server, using the same arguments as -sendres.

Notes:
<param> denotes a required parameter
[param] denotes an optional parameter
address is an address in the form ip address:port. (e.g. 192.168.1.55:25955)
string means a parameter consisting of some combination of letters and numbers (e.g. BoronNoggin)
integer means an integer number must be specified (e.g. 4)
float means a floating point number must be specified (e.g. 3.5)