Command Line Options

David Roberts edited this page Nov 15, 2017 · 8 revisions

User Options

  • --config-path="PATH" - Sets the path to the user configuration area.

  • --difficulty - Sets the game to a given difficulty value; i.e. difficulty=0 or difficulty=casual; can use constants from ~/data/difficulty.cfg which map to integers. Typically used with --level, a later level far into the game, and a cheat code (see frogatto_playable.cfg) to test a later level in the game at a high difficulty level.

  • --fullscreen - Sets the game to start in fullscreen mode.

  • -h, --help - Displays command line usage text.

  • --joystick, --no-joystick - Enables/disables joystick support.

  • --level LEVEL_FILE - Starts the game on the specified level. The LEVEL_FILE is a path to a file, relative to the ~~/data/levels/ directory.

  • --module=modulename - Frogatto's "Anura" engine is now a general 2d game-making system, and has an add-on system which lets us separate packs of game-data into folders; these folders can contain entire individual games (with all of their data, levels, art and sound collected together in one folder), or add-ons for other existing games (such as additional levels for frogatto). We've applied this to frogatto itself, and turned it into a folder just like the others (in fact, the game uses this very option, set in the file ~/master-config.cfg to indicate that it should launch frogatto when you launch the engine. The value passed to this option is the name of a folder inside ~/modules/. Inside that folder there should be a file which automatically sets any other options (like screen size, what other modules it depends on, etc) for that given module, with the intention that a game made in our engine can be launched with just one option.

  • --music, --no-music - Enables/disables the background music. This is a persistent value recorded in the preferences/settings file, and will continue its effect on subsequent launches unless the opposite setting is passed.

  • --native - (Removed.) Sets game resolution to the native resolution of the screen, with one game pixel corresponding to one screen pixel, instead of the default double-sized mode where one game pixel is enlarged to a 2x2 square of 4 pixels. This should be set after the window dimensions are set; without setting them, this defaults to the normal 800x600 screen.

  • --reload-modified-objects - Reload .cfg files that have changed, regardless of if you are in the editor or not. If an object is instantiated from a class, only the base class will get reloaded - the individual instances will not, but they will have the type_updated event fired on them. (example: on_type_updated: "fire_event('create')")

  • --resizable, --no-resizable - Allows/disallows to resize the game window.

  • --scale - turns on a special pixel-art interpolation algorithm (custom, loosely based on 2xSaI) to upscale the game to 2x the size, rather than using the blocky nearest-neighbor interpolation the game currently defaults to. Currently has some visual issues with text and transparent edges; we want to fix the algorithm to categorically solve them, rather than altering content to work around them.

  • --no-send-stats - We phone home anonymous data about a few in-game values: what levels players die on, what levels they quit the game on (intended to diagnose rage-quits), and any asserts/crashes the player has. This disables sending that data entirely.

  • --sound, --no-sound - Enables/disables sound entirely, including music. This doesn't just mute the sound, but completely deactivates the sound-playing code, so audio files will not be loaded (This can save a great deal of ram if you're trying to run on a mobile device.) This is a persistent value recorded in the preferences/settings file, and will continue its effect on subsequent launches unless the opposite setting is passed.

  • --widescreen - Activates widescreen mode; rather than the default 800x600 (4:3) screen size, the game launches with a size of 1066x600 (16:9, with a slight rounding error). The zoom factor stays the same, and the viewable area of the game world increases on the sides to show more content.

  • --width "int", --height "int" - Sets the game window to these dimensions, and stretches the graphics up (or down) to that size.

  • --windowed - Starts in windowed mode.

  • --wvga - Sets the display size to 800x480.

Diagnostic Options

  • --debug, --no-debug - Enables/disables the onscreen display of "debug" output. We have an onscreen console which can be triggered by debug() commands in FFL (our in-game scripting language), and which can be invoked to type in expressions with control-d. This option silences the display of this text, or if the display has been disabled by default (as it is on mobile devices), this can turn it back on.

  • --debug-visualize-audio - Turns on the debug visualization of the audio output. For example, this is useful to see if you're clipping the extremes of the sound wave when you play loud sounds.

  • ----debug-visualize-audio-samples-per-pixel=128 - Sets the horizontal audio scale of --debug-visualize-audio.

  • --debug-visualize-audio-scale=5.0 - Sets the vertical audio scale of --debug-visualize-audio. Larger values mean you can see quieter sounds.

  • --fps, --no-fps - Enables/disables framerate display; displaying framerate by default was something we used to do, but the current default is not to display the FPS indicator, so the latter option is useless at the moment.

  • --potonly - Use power of two-sized textures only. TODO: determine whether this asserts, or pads textures to meet the requirement.

  • --textures16 - This option downsamples our textures to 16bpp, using a 5,5,5,1 rgba scheme if a given texture has nothing more than binary transparency, or a 4,4,4,4 rgba scheme otherwise. This is the default on iOS/mobile devices if you have less than 512mb of ram.

  • --textures32 - This will override a per-platform default to use 16bpp textures and force the game to use our native 32 bpp textures. This is the default on nearly all platforms.

Developer Options

  • --benchmarks - runs all the game's benchmarks (intended to measure the speed of certain low-level functions), prints the results to the console, and then immediately exits the program. Generally only useful if you're actually hacking on the engine to optimize the speed of these.

  • --benchmarks=name - runs just the named benchmark, rather than all of them.

  • --compiled - Uses precalculated tile patterns and object data, rather than calculating which individual graphics should be used for each tile on startup. This is used for performance and memory optimization. Requires that you have an up-to-date set of compiled tile data, which is created by running the game with --utilities=compile_levels.

  • --error-message-box=true - Can be set to false to disable the pop-up box showing the crash error. Defaults to true because, if the modder didn't run Frogatto from the console, then they would never see the message when the game crashed.

  • --max_ffl_recursion=10 - Get a shorter stack trace when recursing to death.

  • --no-compiled - Disables --compiled if the setting defaults to true on a given platform (currently true only on mobile devices), which causes the game to load the regular game data and images instead.

  • --set-fps=10 - Sets the framerate to 10 frames per second (or whatever value you provide), slowing down the action proportionally. That's right - this does not run the game physics at the same speed with less frequent graphical updates; the game-world actually executes slower. This is useful for diagnosing high-speed animations (or other behaviors happening within tiny timeframes - such as anything below 100ms), since at normal playback speed, it's often the case that something behaving incorrectly within those short of timeframes will be really inscrutable - it'll look odd, but contrary to expectations, it often doesn't look obviously wrong/broken. I've had a number of high-speed behaviors like this that I've only been able to diagnose and understand when I slowed them down.

  • --show-hitboxes - Shows the collision boxes for all of the in-game objects. Useful for tweaking said collision boxes to line up right with the actual graphics.

  • --simipad - Changes various options to emulate an iPad environment (mostly screen size and touch-control display).

  • --simiphone - Changes various options to emulate an iPhone environment (mostly screen size and touch-control display).

  • --tests - runs all of the unit tests, prints the results to the console, and then immediately exits the program. Unit tests are sanity checks to make sure you're not breaking something already finished in the game when you add something new. Our default is to run the tests and then launch the game; this differs from that by immediately quitting the game after running the tests.

  • --no-tests - Normally, our unit tests are run automatically on each launch (although they don't exit the program like in the "--tests" option). This causes them not to be run at all.

  • --utility=xx - Allows you to run any chunk of code defined in an instance of UTILITY(xx) { ...bunch of code... } in the existing C++ code. These are documented below.

  • --level-path="path" - Sets the folder to look for levels in. Useful for mod writers.

  • --reload-modified-objects - Watches object files for edits (from an external editor), and immediately reloads them upon being altered.

Experimental MP Options

Frogatto has a functional but unfinished multiplayer system; these set options

  • --host - Sets the game server host address.

  • --relay - Use the server as a relay in multiplayer rather than trying to initiate direct connections through hole-punching.

  • --utility=hole_punch_test TODO

Mod-Specific Options

Any individual module in anura can actually define its own unique options, which can be read inside any object once the game has launched. You can use this to allow any totally arbitrary variable to be set via the command-line when the game launches. There are three parts to using this. First, you need to define what the variables are going to be, within your module.cfg file. You do this by adding: custom_arguments: { some_arg_name: true },

This (for example) would cause the variable to default to true, if the user doesn't actually specify it on the commandline. Second, you'll need to write code that actually uses this object - within your module, it's accessible as the following variable: MODULE_OPTIONS.some_arg_name.

Finally, to actually use the option, you'd run Anura like so: ./anura --some_arg_name=false.

Developer Utilities

  • --utility=document_object_functions - Our FFL scripting language has a collection of functions accessible in it, written in C++. Each of these has inline documentation written in the C++ code; passing this option TODO does something to output this data; I need to determine what.

  • --utility=object_definition - This option launches our in-game code editor, and opens the script file corresponding to this particular object, allowing you to immediately edit it. TODO this is a complete guess, we need to verify if this is true.

  • --utility=correct_solidity - modifies all of our levels, moving any objects which overlap solid terrain (which causes the game to assert) onto open space. Useful if you've modified some object to have a larger hitbox, and most instances of it which were sitting flush on the ground, now overlap the ground. See also --edit, which can be used to get at a broken level by immediately launching the game into the editor (which bypasses the assert).

  • --utility=compile_levels - Precompiles all of our autotiling data into the ~~/data/compiled/ directory in the current module, and precompiles all of our image data into texture atlases at ~/images/tiles-compiled*.png (note; this should be in the current module, but at the time of this writing there's a bug which leaves it at the root engine level). This should be passed immediately before compile_objects.

  • --utility=compile_objects - Precompiles all of our object data into the ~/data/compiled/ directory of the current module, putting the images in texture atlases at ~/images/compiled*.png in the current module. This should be passed immediately after compile_levels, and must be run as a separate launch of the game (i.e. run compile_levels, let the game finish and exit, and then run again with compile_objects instead).

  • --utility=generate_scaling_code - Based on a series of patterns specified in ~/surface_scaling.cfg we auto-generate a C++ file which scales an image to 2x size based on these rules; this gives us a more convenient way to experiment with pixel-art scaling algorithms.

  • --utility=object_editor - TODO

  • --utility=render_level - This generates a PNG, showing the full layout of a given level, useful for walkthroughs, stat-display, or other such things. The background on a level will be drawn as black. Tiles and objects will be drawn in their initial state at cycle 0. TODO lots of guessing here, someone who's used this verify it.

  • --utility=query Example syntax: data/level/ "map(filter(doc.character, value.type = 'ant_black'), add(value.y, -20))" This runs an FFL formula against all levels, allowing us to globally modify data; this can access any FSON value, allowing us to apply nearly any modification to all instances of an object, a tileset, or anything. doc represents the current level, and any sub-values there are the same as nested values in the FSON document.

Note on ~/

When we refer to: ~/, we mean the root level of your frogatto folder. On windows, or unix-built-from-source, this is the same folder the executable is in. On a mac, this is inside the double-clickable Frogatto application, and can be accessed by right clicking on the application, and selecting the menu option "Show Package Contents". This shows a secret folder of what's inside the program, and the ~/ folder is the one inside "Contents" called "Resources".


An option to specify the loading path of a module, so you can have modules such as Frogatto in a different location than your Anura installation, is not provided. You can use symbolic links to get the same effect. For example, instead of --module-path=/modules/go/here, you might create a link on Linux like ln -s modules /modules/go/here.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.