Hard Light Productions Forums

Modding, Mission Design, and Coding => FS2 Open Coding - The Source Code Project (SCP) => Topic started by: jg18 on May 12, 2022, 07:57:31 pm

Title: SEXP Containers: Variables on Steroids (Data Structures for FREDders)
Post by: jg18 on May 12, 2022, 07:57:31 pm
Containers are now documentated on the FreeSpace Wiki (https://wiki.hard-light.net/index.php/SEXP_Container).



As opposed to a SEXP variable, which stores only one value, a SEXP container stores a collection of values.

Consequently, containers allow for handling data in much more sophisticated ways than variables.

Get started with containers using FRED's "Add/Modify Container" dialog, which you can reach from the right-click menu:


The new Replace Container Name/Data submenus are explained below.

Containers come in two types:

Just as variables have a type of either string or number, a container's data and a map container's keys have a type of either string or number.


Feature 1: Replace Container Data


Similar to how Replace Variable allows you to access data stored in variables, Replace Container Data allows you to access data stored in containers.

Use one of the following list modifiers to access data in list containers:

The list modifier options appear in the Replace Data submenu in FRED.

The At list modifier allows you to access data at a specific position in the list. Specify the index using Number under the Add Data submenu. The first item is at index 0.

The Get_*/At list modifiers just retrieve the data, but the Remove_* modifiers both retrieve the data and remove it from the container.

To access map container data, specify the key using Edit Data.

The container modifier can also be the value of a variable (use Replace Variable), the "special argument" if relevant (use Replace Data), or even a nested usage of Replace Container Data.

Restrictions on Replace Container Data usage

You can't use Replace Container Data in the "argument list" of special argument SEXPs, such as any-of, but you can use it in the "condition" or "actions" parts of those SEXPs. This applies for all special argument SEXPs, not just the ones that now take containers as arguments (see Feature 6 below).

Feature 2: Text replacement


Similar to text replacement for variables with $VariableName$, you can access container data in the text used in

For list containers, use the format &ListContainerName&ListModifier&, where [ListModifier is one of the modifiers listed above. To access the first data item in the list, use the modifier At0.

For map containers, use the format &MapContainerName&MapKey&.

Container data and map keys are case-sensitive, but container names and list modifiers are not.

Feature 3: SEXPs and Replace Container Name


You can access the Status and Change SEXPs from the new Containers subcategory in the Status and Change categories for Replace/Insert/Add Operator.

Status SEXPs

Change SEXPs

Conditional SEXPs

FRED's built-in SEXP help explains how they work.

I'm open to adding more SEXPs based on community feedback. :)

To specify the SEXP arguments that are container names, use the Replace Container Name submenu from FRED's right-click menu. You can specify those arguments using Replace Variable or Replace Container Data, too.

Feature 4: Persistence


Containers support the same persistence options that variables do, except for "Network" (Issue #3708).

Feature 5: Multidimensionality





For both text replacement and Replace Container Data, you can chain accesses to container data. The data stored in the first container should be formatted as &ContainerName&.

Unlike the other containers features, there is no equivalent for variables.

Multidimensionality example 1

In the above screen shots, if the random-of in the first screen shot happens to select "Taurus" as the special argument, then the ship "Taurus" will send the message "Ah! A plot is revealed!".

Multidimensionality example 2

If I have two map containers, Map1 and Map2, and I want to display the data associated with the key "Key 1" from one of the two map containers, selected at random, I'd have a list container called Maps whose entries are &Map1& and &Map2&.

The expression to use in text replacement is &Maps&Get_Random&Key 1&.

To do the same thing in FRED's SEXP tree, I'd first use Replace Container Data with Maps using the list modifier Get_Random, and then I'd add "Key 1" using the String option under the Add Data submenu.

Feature 6: Special argument list options


For some SEXPs that are used with when-argument, you can use a mix of strings, list containers of string data, and/or map containers of string keys (map data can be any type) as arguments.

The string data/keys will then be included among the options for the special argument in that SEXP.

When the containers' contents change, the special argument options they provide will change as well.

These SEXPs are supported:

Use the "Replace Container Name" submenu to include containers as arguments.

Restrictions on usage in special argument list

Feature status

As of 22.2 RC1, all features are fully supported.

qtFRED doesn't yet have the Add/Modify Container dialog (Issue #3818) but its SEXP tree should fully support containers.


Please post all questions and comments either in this thread or on the #fred HLP Discord channel.

You can report bugs either here or on GitHub.


This is a continuation (https://www.hard-light.net/forums/index.php?topic=97412.0) of karajorma's work from 2014 (original (https://www.hard-light.net/forums/index.php?topic=88328.0) threads (https://www.hard-light.net/forums/index.php?topic=88613.0)).

Special thanks to
Title: Re: SEXP Containers: Variables on Steroids (Data Structures for FREDders)
Post by: jg18 on May 25, 2022, 11:37:27 pm
The May 26 nightly introduces a couple of breaking changes in how FSO/FRED handle containers, but it's easy to fix your mission files in a text editor with search-and-replace.

(1) SEXP nodes that represent container names should now be &&ContainerName instead of "ContainerName". For example:
Code: [Select]
   ( add-to-list
      ( true )
      "Some Data"

(2) Container names can no longer include spaces.

We made these changes to allow for even more container features. Stay tuned.  :cool: