Session Expressions

Many entities in Frost Helper which accept flags as conditions can instead use Session Expressions. (Check tooltips to see if they are).

Instead of simply checking a single flag, Session Expressions can check multiple flags and even session counters, and perform arithmetic and logic operations on them.

A condition using these Expressions is considered to be met if the value of the Expression is not 0.

Reading Session State

• flagName - Providing a flag name on its own checks if that flag is set, returning 1 if it is, 0 otherwise.
• !flagName - Inverts the logic for checking flags, returning 0 if the flag is set, 1 otherwise.
• #counterName - Reads the value of a Session Counter instead of a flag.
• $deathsHere - Returns how many times the player has died in this room, resets after a screen transition.
• $deaths - Returns how many times the player has died this session.
• $hasGolden - Returns whether the player is carrying a golden berry. 1 if they are, 0 otherwise.
• $restartedFromGolden - Returns 1 if the current session started due to a golden death.
• $coreMode - Returns the current core mode: 0 if not set, 1 if hot, 2 if cold.

Arithmetic

When working with Session Counters, it can be useful to perform arithmetic on them.

You can use basic arithmetic operators: + - * / % and comparison operators <, <=, >, >=, ==, !=

• For example: #counterA + #counterB < 10 checks if the sum of counters counterA and counterB is less than 10.

Because flags get converted to 0 and 1, you can perform arithmetic on flags as well.

• For example: flagA + flagB + flagC == 2 checks if exactly 2 of the 3 provided flags are true.

Logic

&& and || operators can be used to compare 1/0 values, mostly useful for flags:

• For example: (flagA && flagB) || flagC is met if either both flagA and B are set, or flagC. (or all of them at once)
• For example: #money >= #cost && canBuyUpgrades

Session Counter Trigger

Session Counter Triggers support Session Expressions in the Value field (as do many other session counter related triggers) However, there are 2 major differences when using Expressions in them:

• For backwards compatibility, providing a name on its own treats that name as a Session Counter, not a flag! (That is, setting Value to name will read the session counter called name, not a flag! However, name + 2 will read a flag called name!)
• Expressions are treated as returning a number, not a boolean value.

For example, if you want to set a Counter points to the sum of the deaths in the current room plus the value of a Counter bonus:

Interactions with other mods

While other mods might not support this feature, you can still make use of it to control other flag-based entities.

Say you want to change rainbow spinner colors when #money>=5 && otherFlag using a Flag Rainbow Spinner Color Controller.

You can use a Flag If Expression controller entity, which sets a flag if a Session Expression is met, and unsets it immediately when it isn't.

API

Frost Helper provides a MonoMod Export api for creating and evaluating Session Expressions:

[ModExportName("FrostHelper")]
public static class API {
  // ...

  /// <summary>
  /// Creates an object which can evaluate a Session Expression.
  /// The returned object can be passed to <see cref="GetIntSessionExpressionValue"/>
  /// </summary>
  public static bool TryCreateSessionExpression(string str, [NotNullWhen(true)] out object? expression);

  /// <summary>
  /// Returns the current value of a Session Expression as an integer.
  /// The object passed as the 1st argument needs to be created via <see cref="TryCreateSessionExpression"/>
  /// </summary>
  public static int GetIntSessionExpressionValue(object expression, Session session);
}