Mutators

Back

This is a feature for version 1.01.31 of the game.

Other resources

See the Creation Manual for how to create starting configuration files. These are found in WorldNodes/StartingConfig.

The Goal

The goal is to be able to create parameters (bool, int, float, and string) that the user can set when creating a new game. These parameters are passed to the new game. We call these parameters mutators.

Starting Config Files

A package can have multiple starting configuration files. The user selects one when creating a new game with that package. Assume that there is only one starting configuration file WorldNodes/StartingConfig/default_config.txt which reads as follows:

description     "Default configuration"

# Because is_default is defined here
# (and hopefully in no other config file
# in this directory), the following will happen:
# when the player is selecting a new game
# of this package, this config will be highlighted.
is_default

# The node __FBW_DEFAULT__ is special
# because it refers to the root built-in
# world node root for the Xar universe.
root_node       __FBW_DEFAULT__
player_offset   7.5 3 7.5
chunk_path      EMPTY_PATH

# The seed is the default seed used to generate the world.
# If seed_allow_any is set to true, then the user can
# choose a non-default seed (either randomly or by typing it in)
# when creating a new game.
seed 0
seed_allow_any true

#Setting mutators:
#WE WILL ADD MORE HERE LATER!!!

Again, see the creation manual for more on these starting configuration files.

Defining a Bool Mutator

Let us add a bool mutator to our package. In the folder WorldNodes/StartingConfig make sure there is a folder called Mutators. Then in WorldNodes/StartingConfig/Mutators add a subfolder called 1. So now you have the folder WorldNodes/StartingConfig/Mutators/1
This is the folder for the new mutator we are creating. Note: The name of the folder "1" does not matter. The name of the folder only determines what order the mutators show up in when the user is creating a new game.

In the "1" folder, create the following files:

var.txt
about.txt

Let us describe the about.txt file first because it is simple to understand. The about.txt should have text describing the mutator. This text is displayed when the user selects that mutator to modify. Note: The engine adds an extra space at the end of each line and then wraps the line.

The file var.txt sets information about the mutator. Have this file read as follows:

var b lots_of_rockets false
name "Lots of rockets"

The name line specifies the name of the mutator that is displayed in the new game menu.

The var line specifies the actual name of the variable. The variable will be a "global env variable". It also specifies the default value of the mutator. So, in our example, we would need to go to the globals.txt file of the package and add the following line:

b lots_of_rockets false

The actual name of the variable in the engine's environment will be game.globals.lots_of_rockets but you might not need to use that fact.

That is it! Now the player can set the "lots of rockets" variable when creating a new game. Then, the package can read the global variable "lots_of_rockets" with the command

ga_get_b("lots_of_rockets")

and can act accordingly.

Defining an Int Mutator

Defining an integer mutator is almost identical to defining a bool mutator however the var.txt file must also have the following lines

min_i_value -1000
max_i_value  1000

but with -1000 and 1000 replaced with whatever you want. The engine will only let the user select a value for the mutator that is between those two min and max values (inclusive).

Also, the var line would look something like this:

var i int_var 0

Defining a Float Mutator

Defining an integer mutator is almost identical to defining an int mutator however the var.txt file must also have the following lines

min_f_value -1000.0
max_f_value  1000.0

instead of the min_i_value and max_i_value lines. Of course, you can choose your own values instead of -1000.0 and 1000.0.

Also, the var line would look something like this:

var f float_var 0.0

Defining a String Mutator

Defining a string mutator is almost identical to defining a bool mutator.

The var line would look something like this:

var s str_var ""

Hiding a Mutator

You can hide a mutator (have it not show up to the user when they are creating a game) by adding the following line to the var.txt file of the mutator:

hide

You would probably only want to do this if you are setting the mutator from the starting config files, which we will describe next.

Setting a Mutator from Starting Config Files

You can add the following line to a starting config file:

set lots_of_rockets true

Then, when the user selects that starting configuration, it will automatically set the lots of rockets variable to true. Different starting config files could set the variable differently. You could have a mutator which is hidden and each starting config file could set the value of that mutator. Note that if you are setting mutators from starting config files for mutators that are NOT hidden, this might annoy the user.

Passing Variables to Worldgen

Note that you can pass variables to the world generation system. Any global variable that starts with "worldgen.state" is automatically passed to procedural world generation code. So, if you want to pass the "lots_of_rockets" var to worldgen, you would want to use the following variable name instead:

worldgen.state.lots_of_rockets

You could make a mutator for this variable allowing the user to set this while creating a new game. On the other hand, world generation code can access the value of this variable using the Lua function

state_get_b("lots_of_rockets")

Here, the state_get_b function takes a string and automatically prepends worldgen.state to get the actual name of the global variable.