Package Params

Back

This is a feature for version 1.02.02 of the game.

Prerequisites

First read the guide here about mutators because they are similar.

Comparison With Mutators

With mutators, when the player starts a new game, they can set the values of "mutators" in the new game menu. These values are remembered for the next time the player creates a new game using that standalone package. When a new game is actually created, these mutator variables are copied into (global) environment variables which the package can access. The package can even modify those environment variables, but since they are just copies this does not affect any other saved game. There is no way to change the package vars where the mutators are stored from Lua code (because they are non-global package vars).

Package params, on the other hand, are not copied to global environment variables and instead only exist as (global) "package variables". See the creation manual for how to get and set (global) package variables from Lua code (with functions like ga_package2_set_i, etc). Note that package params are associated to the package and not the saved game, so changing package params affects all saved games that use that package.

How The User Can Change Package Params

The user can change the value of package params by going to

Options → Mods → Mod Params
and using the menu. No saved game needs to be loaded when doing this.

The Unique Package Name

If your mod is called mymod and is located in the Data/Packages folder of the game, then the unique package name of your mod is just mymod. On the other hand, if your mod is located in the Input/Packages folder, then your unique package name is __USER__mymod. That is, we prepend the literal string "__USER__" to the front of packages in the Input/Packages folder.

This is important because when you get and set package variables using functions like ga_package2_get_i and ga_package2_set_i, you use the unique package name for the package name.

Steam Workshop Warning

When you upload your mod to the Steam Workshop for the first time, the game will change the name of the package by adding @XXXXXX at the end for some number XXXXXX. So, you will need to upload to the Steam Workshop first before you know the exact name of your package. You need to know that name of your package in order to get and set package params from Lua code.

Declaring Package Params in a Mod

Let's say you have created a mod called mymod. Here is how to declare package parmas for your mod. In your mod package, create the file

WorldNodes/StartingConfig/PackageParams/default_values.txt
(capitilization matters). This file specifies the names of all package params in your mod as well as their type and default values. This contrasts with mutators, where we do not have such a file. This file is read in by the engine every time a game is loaded that uses your mod. It is also used by the menu for changing package params. Here is an example of what the file can look like:

#This is a comment.
b var_bool false
i var_int 5
f var_float 3.14
s var_string "Bobby bobby bob bob"

The only allowed types for package params are bool (b), 64 bit int (i), 64 bit float (f), and string (s). The syntax of each (non-comment line) is the type character followed by var name followed by default value. The var name can only include letters, numbers, underscores, and periods (otherwise there will be undefined behavior).

Describing a Bool Package Param

To have a bool package param, first it must already be declared in the default_values.txt file. Then, create a subfolder in

WorldNodes/StartingConfig/PackageParams/
(the name does not matter). Let's say the subfolder is called VarBool. Then, within the var bool folder you should create the files about.txt and var.txt.

The about.txt file is just text which describes the package param. This is displayed to the user in the menu where they can change the value of the param.

The var.txt file should look something like this:

var var_bool

name "Bool var"

The "name" line specifies the human readable name of the param which will be shown to the user in the menu to change package params. The xar package param naming convention for these is to have the first letter capitalized but not the rest.

The "var" line specifies the name of the variable itself. This must appear in default_values.txt files. In our example the variable is var_bool. It is actually stored as a package variable using the full name

package.state.globals.var_bool
If you go to Data/PackageState/ and go to the package's folder and open the vars.txt file you can see all the package variables that are stored for the package. To actually modify the var from Lua code in your mod, you can use code like

local value = ga_package2_get_b("__USER__mymod", "var_bool")

Describing an Int Package Param

A (64 bit) integer package param is just like a bool package param except the var.txt file also needs to specify the min and max value for the param. Here is what the var.txt file could look like:

var var_int

name "Int var"

min_i_value -200
max_i_value 200

Describing a Float Package Param

A (64 bit) float package param is just like a bool package param except the var.txt file also needs to specify the min and max value for the param. Here is what the var.txt file could look like:

var var_float

name "Float var"

min_f_value -12.5
max_f_value 36.7

Describing a String Package Param

A string package param is just like a bool package param. Here is what the var.txt file could look like:

var var_string

name "String var"

Printing Package Params During Game Loading

In a game Lua script you can print the values of these variables when the game is loaded:

function p.get_package_name()
    return "__USER__mymod"
end

function p.__load_game()
    local package_unique = p.get_package_name()
    local value_bool   = ga_package2_get_b(package_unique, "var_bool")
    local value_int    = ga_package2_get_i(package_unique, "var_int")
    local value_float  = ga_package2_get_f(package_unique, "var_float")
    local value_string = ga_package2_get_s(package_unique, "var_string")
    --
    ga_print("value_bool:  " .. tostring(value_bool))
    ga_print("value_int:   " .. tostring(value_int))
    ga_print("value_float: " .. tostring(value_float))
    ga_print("value_str:   " .. value_string)
end

Download

Here is a package that is similar to what we have described. You install it in the Input/Packages folder of the game.