Difference between revisions of "Command-Line Reference"

From FreeSpace Wiki
Jump to: navigation, search
(-height was replaced with -noheight in 3.6.15)
(Adds the -profile_frame_time cmdline parameter introduced in rev 9806)
Line 381: Line 381:
  
 
Jump into the mission specified by the filename.  Only in effect on the first run. This will skip load of the mainhall and its other related things altogether.
 
Jump into the mission specified by the filename.  Only in effect on the first run. This will skip load of the mainhall and its other related things altogether.
 +
 +
====-profile_frame_time====
 +
'''"Profile engine subsystems"'''
 +
 +
Activates the frame profiling code. This presents a readout showing the current, minimum, maximum and average percentages of frametime a given section of code has taken up; this can be used to identify particular bottlenecks or measure the effectiveness of certain optimizations.
  
 
==Other==
 
==Other==

Revision as of 08:06, 21 September 2013

Command-Line Flags (also called Command-Line Parameters) are optional flags passed to the FSO executable, and generally enables one or more features added to the FS2 Open engine. These flags are accessed conveniently through an FSO Launcher. To have FSO list all available flags, use any one of the following: -help, --help, -h, or -?.


Contents

Graphics

-spec

"Enable Specular"

Only polygons mapped with textures for which a shinemap exists will receive specular mapping; no attempt is made to generate spec maps where they do not exist. Specular maps are specified with the base map name plus "-shine" (i.e. TCov3A-shine.pcx).

FS2 Open, 3.6.16:
  • This feature is on by default, use launcher option Disable Specular or if necessary to manually disable enter the flag -nospec

-env

"Enable Environment maps"

It only works if -spec is also set. Environment mapping intensity will be determined from the shine map too (see Texturing for more info). See Video setup.

FS2 Open, 3.6.16:
  • This feature is on by default, use launcher option Disable Environment Maps or if necessary to manually disable enter the flag -noenv

-glow

"Enable Glowmaps"

Only polygons mapped with textures for which a glowmap exists will be glowmapped. Glow maps are specified with the base map name plus "-glow" (i.e. TCov4A-glow.pcx)

FS2 Open, 3.6.16:
  • This feature is on by default, use launcher option Disable Glow Maps or if necessary to manually disable enter the flag -noglow

-nomotiondebris

"Disable motion debris"

-noscalevid

"Disable scale-to-window for Movies"

Disables fullscreen scaling of video clips.

-missile_lighting

"Apply Lighting to Missiles"

-normal

"Enable Normal Maps"

Normal maps require GLSL rendering, (see OpenGL Shaders (GLSL) for further info). It needs auxiliary normal maps (the same name of the base map plus "-normal"). DXT5_NM DDS format is needed. (Technical note: DXT5 will work, since only the GREEN and ALPHA channels are read by the current shader system. One direction of lines goes into the GREEN channel, the other direction goes into the ALPHA channel. RED and BLUE can be either base gray (#808080) or black. Usual practice is after creating the DXT5_NM, copy the RED channel to the ALPHA channel, black out the RED and BLUE an then save as either a DXT5 or u8888 (uncompressed) DDS file.)

FS2 Open, 3.6.16:
  • This feature is on by default, use launcher option Disable Normal Maps or if necessary to manually disable enter the flag -nonormal

-post_process

"Enable Post Processing"

enables the use (if present) of post-processing effects as defined by the post_process.tbl. Bloom usage has an additional cmdline option for setting it's value, most post processing effects are achieved in mission per the mission designer or can be enabled globally in the table.

-soft_particles

"Enable soft particles"

-3dshockwave

"Enable 3D Shockwaves"

This only has any effect when both a 2d and 3d shockwave effect are present, otherwise the only available effect is used.

-fxaa

"Enable FXAA antialiasing"

Enables the FXAA postprocessing stage. Further information can be found here: http://www.hard-light.net/forums/index.php?topic=76145.0

-flightshaftsoff

"Force Lightshafts off"

Disables Lightshafts even if a mission designer enables them via SEXP in a mission.


Game Speed

-img2dds

"Compress non-compressed images"

Converts all images to DDS (compressed) format. Decreases memory usage but potentially reduces image quality.

-no_vsync

"Disable vertical sync"

-cache_bitmaps

"Cache bitmaps between missions"

Will ideally reduce the load-time from one mission to another.


HUD

-dualscanlines

"Another Pair of Scanning Lines"

Adds a second pair of scanning lines to the target window when scanning an object.

-targetinfo

"Enable Info next to Target"

Displays target info, such as name and class, beside the targeted object.

-orbradar

"Enables 3D radar"

An Orb style 3D radar will replace the standard 2D version.

-rearm_timer

"Enable Rearm/Repair Completion Timer"

Displays time remaining until rearm and repair from a support ship is complete.

-ballistic_gauge

"Enable the analog Ballistic Ammo gauge"

Adds an ammo gauge to the HUD when armed with a ballistic weapon.


Gameplay

-ship_choice_3d

"Use Models for Ship Selection"

Uses ship models in ship selection window. It completely disables the standard ANI interface in this screen.
Some mods need a compulsory use of this flag because they don't have available animations for their ships. In this situation, and if it is not used, the game will probably crash to desktop in the ship selection window.

-weapon_choice_3d

"Use Models for Weapon Selection"

Uses weapon models in weapon loadout window for secondary weapons (missiles and bombs). It completely disables the standard ANI interface in this screen.
Some mods need a compulsory use of this flag because they don't have available animations for their secondary weapons. In this situation, and if it is not used, the game will probably crash to desktop in the weapon loadout window.

-3dwarp

"Enable 3D Warp"

Use full geometry for the subspace warp effect.

-warp_flash

"Enable Flash upon Warp"

Enable a flash at warp in and warp out.

-no_ap_interrupt

"Disable Interrupting of AutoPilot"

Tells the game to not allow players to interrupt an autopilot already-in-progress.


Audio

-snd_preload

"Preload mission game sounds"

Useful in preventing game stuttering when sounds are played for the first time.

-nosound

"Disable Sound and Music"

-nomusic

"Disables Music"

Multiplayer

-standalone

"Run as Stand Alone Server"

Creates a standalone multi-player server.

-startgame

"Skip Mainhall and Start Hosting"

Once you launch and choose a pilot within the game, you will immediately have begun to host a game. This can be used in conjunction with several options to customize the game you create: -closed, -restricted, -password, -gamename, -allowabove, and -allowbelow. -startgame has no effect when -standalone is used.

See related: -closed -restricted -password -gamename -allowabove -allowbelow

-closed

"Start Hosted Server as Closed"

Hosts a new game in a closed state, where no one can join until the in-game "Close" button is cleared. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -restricted or -password.

See related: -startgame -restricted -password

-restricted

"Host Confirms Join requests"

Hosts a new game in a restricted state. The host is presented with option to accept or deny each client's request to join the game. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -closed or -password.

See related: -startgame -closed -password

-multilog

Creates a log file with a summary of packets sent and received in multiplayer games. The file is saved as \data\multi.log within the active mod folder—or with main data folder if no mod is active.

-clientdamage

This feature is not available in current builds.

-mpnoreturn

"Disables Flight Deck option"

Disables return to the flight deck screen after a mission completes.


Troubleshooting

-nohtl

"Software Mode (very slow)"

Warning: Enabling this will significantly reduce performance.

Reverts to software rendering mode.

-no_set_gamma

"Disable Setting of Gamma"

Disables the gamma settings in the options screen.

-nomovies

"Disable Video Playback"

Disables all video playback.

-noparseerrors

"Disable Parsing Errors"

Disables some parsing warnings and makes other parse errors non-fatal. Do not rely on this when creating new tables. The errors are there for a reason.

-safeloading

Loads missions the old way. Typically safer, but slower.

  • Note: the parameter was removed as of the July 5, 2011 nightly build.

-query_speech

"Does this build have Speech?"

Determines if the current build includes text-to-speech.

-novbo

"Disable OpenGL VBO"

-noibx

"Don't use cached index buffers (IBX)"

Disables IBX caching of model geometry data. This will dramatically increase load times, but will help troubleshoot a model if one is working incorrectly.

-loadallweps

"Load all weapons, even those not used"

-disable_fbo

"Disable OpenGL RenderTargets"

-no_glsl

"Disable GLSL (shader) Support"

Disables the use of GLSL rendering (OpenGL shaders). The game will revert to legacy fixed render pipeline. Please note that Normal and Height map effects will be unavailable.

-disable_glsl_model

"Don't use shaders for model rendering"

-ati_swap

"Fix Color issues on some ATI cards"

-no_3d_sound

"Use only 2D/stereo for sound effects"

-disable_di_mouse

"Disables the DirectInput mouse code for FSO on windows."

Windows Only Can make mouse movement smoother on certain machines.

-mipmap

"Enable mipmapping"

Causes for non-mipmapped textures to have mipmaps generated within the GPU on certain kind of texture formats, (IIRC, DDS formatted textures with a power of 2 size in both width and height).
Since the use of already mipmapped DDS textures has become common, it has become deprecated. The quality of the generated mipmaps depends on each GPU and used driver. It is normally used with -img2dds flag.

Experimental

-ingame_join

"Allows Ingame Joining"

Enables ingame joining in multiplayer. FIXME: Host option?

-voicer

"Voice Recognition"

Windows-only. Enables voice-recognition for wingmen commands. Must be specifically compiled into a build in order for it to be available; 3.6.10 final includes the feature. See Voice Recognition for more details.

Development Tools

-fps

"Show frames per second on HUD"

Displays current frames per second.

-pos

"Show Position of Camera"

Displays current position coordinates of camera.

-window

"Run in Window"

Runs the game in a window. No check to make sure that resolution is no higher than your desktop resolution, so be careful.

-fullscreen_window

"Run in Fullscreen Window"

-timerbar

Displays a timing bar across the top of the screen. Timerbar format varies by build. This is a relic from the Volition development days, and is unmaintained.

  • Note: the parameter was removed as of the July 5, 2011 nightly build.

-stats

"Show Statistics"

Shows total and free physical memory, virtual memory and system pagefile.

-coords

"Show Coordinates"

Shows coordinates of the mouse cursor.

-show_mem_usage

"Show Memory Usage"

Shows detailed RAM usage based on file, handler and process usage and display on the left-center side of the screen during mission load and while in mission.

The meaning of the info displayed in the upper right corner of the HUD is:

DYN = dynamic memory, basically anything that's been allocated by the vm_* memory functions. This does NOT indicate total memory usage but does account for most of it.

POF = model memory, how much memory is being used by models (does not include textures)

C-BMP, BMP = bmpman memory, how much is used by the textures/images that are loaded. C-BMP means that you are using -cache_bitmaps and it will try to keep textures in memory between level loads and as the new level is loading it will keep what it needs and unload what it doesn't. Can greatly increase level loading speed, but does so at the cost of memory between level loads. This does not increase overall memory usage though, only during the loading screen. BMP means that it is not cached and all textures are unloaded from memory at the start of level load and all needed textures are then loaded from the disk again.

S-RAM = sound memory, how much is used by the sounds loaded in memory at the time. This counts static sounds only (from sounds.tbl, etc.) and not streaming sounds (music, voices, briefing stuff, etc).

V-RAM = approximate memory usage of video textures. This does not mean that your card has this much memory, and can report higher numbers that your card actually has memory. For OpenGL it also includes some of the geometry data, but this number does not reflect the total memory that your video card is using. It only reports how much data the game has purposefully loaded into API memory (meaning it could be in system memory, video card memory, or AGP memory).


(It only works with debug builds, not with release builds).

-pofspew

Reads all objects in the pof file of the selected mod, and creates an ibx cache file for each object in the data/cache folder for that mod.
Details for each object are output to a pofspew.txt file created in the data folder.
Otherwise, ibx files are created in game before each mission.

-tablecrcs

Is actually now (or should be) a typed reference rather than as a selection item. Takes 1 argument, usually a descriptive name. Example usage: "-table_crcs MediaVPs" will create a table_crcs.csv file in the running mod (name can be separate of the mod selected) that allows for the validation of the tables used by that mod while on-line. The descriptive parameter given helps "allocate" that .csv file to the mod in question, and as such should closely or exactly match that mods name if possible.

-missioncrcs

Is actually now (or should be) a typed reference rather than as a selection item. Takes 1 argument, usually a descriptive name. Example usage: "-mission_crcs MediaVPs" will create a mission_crcs.csv file in the running mod (name can be separate of the mod selected) that allows for the validation of the missions used by that mod while on-line. The descriptive parameter given helps "allocate" that .csv file to the mod in question, and as such should closely or exactly match that mods name if possible.

-dis_collisions

"Disable Collisions"

Disables all collisions.

-dis_weapons

"Disable Weapon Rendering"

Disables weapons rendering.

-output_sexps

This will make the FSO build spit out an html file that documents the supported SEXP's.

Just double click on sexps.html and it should open in your default web browser.

-output_scripting

This will make the FSO build spit out an html file that documents the supported scripting hooks and LUA libraries.

Just double click on scripting.html and it should open in your default web browser.

-nograb

Unix only. Disables focus grabbing in a window.

-save_render_target

"Save Render Targets to file"

-debug_window

"Display Debug Window"

Lists the fs2_open.log in (nearly)real-time generation.

-verify_vps

"Spew VP crcs to vp_crcs.txt"

Exports the CRC values of the VP files being loaded into a vp_crcs.txt file.

-reparse_mainhall

"Reparse mainhall.tbl when loading halls"

Mainhall.tbl will be reparsed every time a mainhall is loaded, as opposed to just once at game startup.

-start_mission

"Skip the mainhall in jump right into the specified mission"

Jump into the mission specified by the filename. Only in effect on the first run. This will skip load of the mainhall and its other related things altogether.

-profile_frame_time

"Profile engine subsystems"

Activates the frame profiling code. This presents a readout showing the current, minimum, maximum and average percentages of frametime a given section of code has taken up; this can be used to identify particular bottlenecks or measure the effectiveness of certain optimizations.

Other

The following options are not available as checkboxes in the launcher. Many require parameters, which follow the flag separated by a space. The prototype for use in this case is "-option argument"

Lighting

These factors can dramatically alter the atmosphere of the game. This page has some sample lighting settings with screenshots.

-ambient_factor

This must be entered into the "Custom flags" field. This is a multiplier applied to the intensity of ambient lighting. Ambient light is lighting applied to all parts of a ship. FS2's standard value is 120. Try 75 for a good and realistic looking value. However, that is relative.

-no_emissive_light

By default, all ships in FS2 have a light generated on their own, it is more or less similar to a minimal amount of -ambient_factor. This feature was implemented to help the player seeing the ships over a black background. This flag disables this feature. Use it with a low -ambient_factor value to obtain an ultra-realistic dark looking.

-spec_exp

This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts the size of the shiny spot on ships. Higher number mean smaller spots. Default is 16. However, 11 is recommended. This is a relative value.

-spec_point

This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts how much laser weapons contribute to specular highlights. Higher number mean greater contributions. Default is 1.0. However, 0.6 is recommended. This is a relative value.

-spec_static

This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts how much suns contribute to specular highlights. Higher numbers mean a greater contribution. Default is 1.0. However, is 0.8 recommended. This is a relative value.

-spec_tube

This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts how much Beam Weapons contribute to specular highlights. Higher numbers mean a greater contribution. Default is 1.0. However, 0.4 is recommended. This is a relative value.

-ogl_spec

Takes a numerical argument. This value changes the basic shininess of the specular light in OpenGL. A lower value reduces the overall intensity of the light making it broader and less powerful. A higher value makes it more focused and brighter. The default value is 80, and the usable range is 0 to 128 (clamped). The original default value was 60, but it was raised to behave more D3D like.


Graphics

-bloom_intensity

Requires -post_processing ("Enable Post Processing") command. Default value is 75. Range is 0-200.

-height

Enables height maps (parallax mapping). It only works if -normal is also set. It also needs GLSL rendering, (see OpenGL Shaders (GLSL) for further info). It needs auxiliary height maps (with the same name than base map plus "-height").

FS2 Open, 3.6.16:
  • This feature is on by default. To manually disable, enter the flag -noheight

-clipdist

Changes the distance from the viewpoint for the near-clipping plane.

Takes one argument decimal specifying the distance to the near-clipping plane.

-res

Allows you to specify a resolution if the desired one cannot be set in the Launcher. For example, -res 1920x1080 would run the game in 1920 x 1080 resolution. Since it requires an argument, it needs to be entered as a custom flag when using the Launcher. The "Run at specified resolution" option the Launcher gives is essentially this, but without being able to actually specify a resolution, it doesn't work.

-fxaa_preset

Requires both -post_processing and -fxaa. Can be used to adjust the FXAA quality and speed, 0 is fastest, 9 is highest quality. Default setting is 6.

Gameplay

-mod

Specifies in which folders inside FreeSpace 2 directory, the game looks for all the game data (models, missions, textures, tables, ...). Retail version only looks inside Freespace2/data/ structure and Freespace2/vp archives.

This flag allows installing several different mods that modify retail behavior, and switching between them without needing to erase files or having undesired cross effects. Each mod should be installed in its own folder.

It takes one argument string: the chain of names of the used directories. Comma (,) must be used as separator. In this way, -mod dir1,dir2,dir3,...,dirx causes the game to use the following directory precedence:

  1. Freespace2/dir1/
  2. Freespace2/dir2/
  3. Freespace2/dir3/
  4. ... (the rest of the typed directories) ...
  5. Freespace2/dirx/
  6. Freespace2/

This flag can be indirectly set, (and it is normally set), through Launcher MOD tab and mod.ini file.

Within the Launcher's MOD tab you can select one directory, (let's call it moddir), so the flag is at least set to -mod moddir. If Freespace2/moddir/mod.ini exists it will be used to modify the -mod flag, too.

For further details, see mod.ini

Data precedence

As already said, within the different directories, the data precedence is set by the specified order in the -mod flag. The lowest priority goes to the Freespace2 installation directory.

Inside each directory, data precedence is the following:

  1. Individual files located in Current_dir/data/ subdir structure. See FS2 Data Structure topic for deeper info about the different folders and contents this structure has.
  2. Files located inside vp archives. (These vp archives are "similar" to zip archives. They just contain other files and folders. Moreover, files have to be stored using the same data/ structure used outside it).
    Vp archives are read in alphabetical order, so aaa.vp files have higher priority than aab.vp files and so on.

The highest priority file overrides the rest of them. In this way, if you have a Mission.fs2 inside Freespace2/Pri1/data/missions/ it doesn't matter that this Mission.fs2 is also inside Freespace2/Pri1/aaa.vp, Freespace2/Pri1/aab.vp, ... or Freespace2/data/missions/. This data precedence allows the user to quickly replace old files by corrected or enhanced ones adding them in a higher priority place.


Additional notes

  1. As derived from the explanation, the exact names for directories or vp archives are actually irrelevant. It only matters the directory order inside -mod flag argument and the alphabetical order for vp archives inside each used directory.
  2. This flag is also used by FRED. So if there is special mod info, (like backgrounds maps, ship models or whatever), it must be typed, (Fred2_Open_r.exe -MOD whatever), or FRED won't be able to use it. A special build of wxLauncher is able to configure FRED so that the -mod doesn't have to be done manually see the forum post for more details.
FS2 Open, 3.6.12: As of 3.6.12 FRED now loads cmdline_fso.cfg just like FS does so FRED will use the same settings as FS including the -mod settings
  1. Be careful while typing the directory names in the flag argument or inside mod.ini files. The program doesn't check if the typed directories exist. If they do not exist, they are just ignored. No warnings, no errors, no messages at all.


Warning: Priority and Texture Formats

Obsolete behavior - Until FS2_open v3.6.9.:

FS2_Open can use several file formats in textures: PCX, DDS, JPG and TGA. Make sure you keep the format when you update your texture. For example if you update the old TextureOfMyFighter.tga, do not save it as TextureOfMyFighter.dds in a higher priority place, because there is a chance of the game loading the old one despite of all.

The reason to do this is that, loading process (including priorities) is applied firstly for a kind of textures (TGAs), then for another kind (JPGs), and so on. This behavior can lead to situation where your new, updated and higher priority placed texture is not read because the format of the older one.


New behavior - From FS2_open v3.6.10. (including previous beta testing releases):

The former issue has been fixed. Now texture format priority is only applied within the same location. In this strange situation it goes DDS -> TGA -> JPG -> PCX. Examples:

  • /Freespace2/MyVp.vp>>>data/maps/MyTexture.dds is loaded instead of /Freespace2/MyVp.vp>>>data/maps/MyTexture.tga.
  • But your improved /Freespace2/data/maps/MyTexture.xxx will override them both despite of its format.

In this way, when you update any texture, you don't have to pay attention to its original format. Just place it in a higher priority place.

Nevertheless, global priority is kept between animated and static textures. Because of their management, animated textures (ANIs and EFFs) are looked for BEFORE static ones. In this way there's no way to update an animated texture with a static one (an obsolete ANI is always going to be loaded before the newer DDS version). The solution: use an updated EFF with just one frame.

-fov

This flag allows the player to specify the vertical Field of View (FoV) angle, in radians, for the player eyepoint. The angle is measured across the full width of the viewing cone. The FoV angle is technically known as the Angle of View (AoV)

  • Syntax: float Angle
  • Valid Values: 0 to 2*Pi radians
  • Default Value: 0.75 radians


The the FoV angle/AoV is what determines the relative zoom level of the main game camera. Smaller angles generally equal to higher zoom levels, while larger angles equal to lower zoom levels (down to the theoretical x0 magnification).


However, too small of an angle will have a squashed look on the edges of your screen, and too high of an angle will greatly stretch edges. It is recommended to change the AoV, as FS2's default AoV has some perspective distortion at the screen edges (the default AoV is too high).


A natural looking (as if you where physically in the cockpit) AoV depends on the distance the player's actual eyes are away from the screen: the further away from the screen, the smaller the AoV should be, and vice versa. "Ergonomic" distances generally yield a diagonal AoV of 0.523 radians (30 degrees), but you can easily find the natural AoV by the following formula:


AoV (radians) = atan( H / ( 2*D ))

where:

Height of screen = H

Distance between head/eye and the screen = D


Generally, gamers like to increase the AoV in order to increase their peripheral vision on the screen, so as to gain a better situational awareness around their craft. An AoV of 0.39 radians seems to be a good start, but feel free to experiment and use whatever AoV you are most comfortable with.

Multiplayer

-gamename

Specifies the name of the game to be created by the host. This only works when used in conjunction with -startgame.

Takes one argument string, the name to be assigned to the game being created.

This argument does nothing when used with -standalone. To set the name for a standalone server, see Standalone Servers.

See related:   -startgame   Standalone Servers

-password

Specifies the password for a standalone server. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -closed or -restricted.

Takes one argument string, the required password for the game being created.

See related: -startgame -closed -restricted

-allowabove

Specifies a player's minimum rank for joining a game. This only works when used in conjunction with -startgame.

Takes one argument integer, the points ranking above which a player must be to enter the game.

See related: -startgame

-allowbelow

Specifies a player's maximum rank for joining a game on a standalone server. This only works when used in conjunction with -startgame.

Takes one argument integer, the points ranking below which a player must be to enter the game.

See related: -startgame

-port

Specifies the port on which to host a game or serve a standalone game.

Takes one argument integer, the port on which the host will listen for clients.

-connect

-timeout

-cap_object_update

Caps the maximum object update the server will respond to regardless of what the client has set. If the client is set to request high object updates but the server is capped to low, then that's all the client will get.

Takes one argument integer (0 to 3) which corresponds to the object update cap (With 0 being low and 3 being LAN).


Help

-help

Instructs FSO to print out all supported parameters. Some launchers can use these options to automatically populate the available command line options, even if the version of FSO is far newer than the launcher itself. NOTE: This option only works in Linux builds...

--help

See -help

-h

See -help

-?

See -help