Modding Documentation

The following documentation aims to help creators integrate many of the different features of the Starstorm mod into their own mods.

***Note that Starstorm must be added as dependency (can be set to optional).***

## **Callbacks:**

* **“postPlayerStep”** (player): Fired at the end of each frame for each player.
* **“onActorStep”** (actor): Fired every tic for each actor instance.
* **“postStageEntry”** (stage): Fired a frame after entering a stage.
* **“onTrueActorInit”** (actor): Fired at the end of the first frame of every newly created actor, also accounts for irregular actors like worm segments.
* **“onSSInteractableAction”** (object, player): Fired on activating a SSInteractable.
* **“onSkinInit”** (player, skin): Fired for each survivor after the variant selection menu.
* **“postSelection”** (): Fired after the variant selection menu.
* **“onExtraDifficultyUpdate”** (number): Fired after entering an ethereal teleporter, as the difficulty is changed.
* **“onGameBeat”** (endType): Fired after beating the game.

## **Survivor Variants:**

### **Fields:**

* **displayName** (String): The displayed name of the variant.
* **loadoutSprite** (Sprite): (Optional) The sprite of the skin in the selection menu.
* **color** (Color): (Optional) Defaults to the survivor's color. A color for the variant's skill names and stats chart.
* **animations** (Table): (Optional) A table containing the sprites that will be used by the variant. Each sprite's index must be the name of the animation.
* **hidden** (Boolean): (Optional) If set to true, the variant will be invisible and non selectable.

**Example valid animations table:**

myVariant.animations = {

idle = Sprite.load ( ... )

jump = Sprite.load ( ... )

shoot1\_1 = Sprite.load ( ... )

shoot1\_2 = Sprite.load ( ... )

shoot2 = Sprite.load ( ... )

}

### **Functions:**

Custom variants can be added by using the following functions:

#### **SurvivorVariant.new( Survivor, SkinName )**

Creates a new survivor variant for the passed survivor, returning the variant.

**Parameters:**

* **Survivor** (Survivor): The Survivor to add the variant to.
* **SkinName** (String): The name of the variant.

#### **SurvivorVariant.find( Survivor, SkinName )**

Returns the variant as searched by name, nil if none found.

**Parameters:**

* **Survivor** (Survivor): The Survivor parent of the variant.
* **SkinName** (String): The name of the variant to search for.

#### **SurvivorVariant.getActive( PlayerInstance )**

Returns the active variant of the passed Player Instance.

#### **SurvivorVariant.setDescription( Variant, Description )**

Sets the description of the variant in the selection menu.

**Parameters:**

* **Varian**t (SurvivorVariant): The variant to set the description to.
* **Description** (String): The text of the description. Supports colored text formatting.

#### **SurvivorVariant.setLoadoutSkill( Variant, Name, Description, Image, [SubImage] )**

Sets a selection menu skill display for the passed variant.

**Parameters:**

* **Variant** (SurvivorVariant): The variant to set the skill to.
* **Name** (String): The title of the skill.
* **Description** (String): The text of the description. Supports colored text formatting.
* **Image** (Sprite): The sprite of the skill.
* **SubImage** (Number): The subimage of the sprite used by the skill.

#### **SurvivorVariant.setInfoStats( Variant, Stats )**

Sets the stats of the variant for the selection menu.

**Parameters:**

* **Variant** (SurvivorVariant): The variant to set the stats to.
* **Stats** (Table): A numerically indexed table containing the stats to display in graph form.

**Example:**

{

[1] = {"Strength", 5},

[2] = {"Coolness", 10}

}

The first value in every entry is a **string** for the name of the stat, the second is the value of the stat (from 0 to 10).

#### **SurvivorVariant.setRequirement( Variant, Achievement )**

Sets an achievement parent for a variant.

**Parameters:**

* **Variant** (SurvivorVariant): The variant to set the requirement to.
* **Achievement** (Achievement): A valid achievement to link to the variant.

The achievement's description field is used in the selection menu when hovering over the locked variant.

### **Callbacks:**

Currently skins have one callback:

**onSkinInit**: Triggered for every player when the game starts, after the skin selection menu.

This callback must be used instead of a survivor’s “init” callback or “onGameStart” for setting a custom variant’s starting variables and stats.

It passes the PlayerInstance followed by the Skin object.

**Example:**

callback.register(“onSkinInit”, function(player, skin)

   If skin == myVariant then

       player:set(“pVmax”, 5)

   end

end)

Sets myVariant’s initial jump height to a value of 5

## **Ruleset Rules:**

### **Fields:**

* **id** (Number): Read only.  This is the internal identification for the rule.
* **displayName** (String): Determines the displayed name of the rule, can override the name set through *Rule.new()*.
* **type** (String): Determines the type of value the rule can store. Can be either "checkbox" or "choice", note that a checkbox rule can only hold *boolean* values.
* **default** (Value): The default value of the rule. If the type is "choice" this must be set to one of the values inside the "options" field table (See below).
* **tooltip** (String): The text shown when hovering over the rule.
* **isSub** (Number): the id of the parent rule, if this rule requires another.
* **Exclusive for "choice" type rules:**
* **options** (Table): The different options / choices that can be picked from.
* **isString** (boolean):  This will only make the display fit the strings correctly. It can be used with numbers too if needed.
* **prefix** (String): The prefix of the rule value in display, e.g.: "**+** 20".
* **suffix** (String): The suffix of the rule value in display, e.g.: "100 **%**".

### **Functions:**

Mod rules can be added and read by using the following functions:

#### **Rule.new( Name )**

Creates a new rule that can be tweaked in-game through the ruleset menu.

**Parameters:**

* **Name** (String): The displayed name of the new rule.

**Returns:**

Always returns a new rule.

#### **Rule.find( Name, Category )**

Finds a rule by its name and category.

**Parameters:**

* **Name** (String): The displayed name of the new rule.
* **Category** (String): The category the rule is to be found in.

*Categories: "Global", "Players", "Enemies", "Misc", "Other Mods".*

**Returns:**

If the rule is found, returns the rule, nil otherwise.

#### **Rule.getSetting( Rule )**

Gets the value of the current rule in the active ruleset.

**Parameters:**

* **Rule** (Rule): The rule to get the value from.

**Returns:**

Returns the value stored in the rule by the active ruleset.

## **Tab Menu Info:**

Mod items can be added to the menu's information database by using the next function:

#### **TabMenu.setItemInfo( Item, [MaxStack], [Info], [StackInfo] )**

Creates (or replaces if it already exists) special information for the passed item to display when the item is hovered on the info menu.

**Parameters:**

* **Item** (Item): The item object to set the information to.
* **MaxStack** (Number): The maximum number for stacking the item.
* **Info** (String): The specific information about the item.
* **StackInfo** (String): How stacking affects the item.

## **Events**

### **Fields:**

* **id** (Number): Read only. This is the internal identification for the rule.
* **alert** (String): This is the displayed message once the Event is starting.
* **baseDuration** (Number): The base duration of the event in seconds.
* **durationScaling** (Number): The amount of seconds added to the duration per scaling level.
* **randomEventChance** (Number): The chance per frame for the event actions to trigger.
* **persistent** (Boolean): Whether the Event can persist through stages.

### **Functions:**

Custom Events can be integrated through the following functions:

#### **Event.new( Name, [OnStep], [OnRandomEvent], [OnEnd] )**

Creates a new Event.

**Parameters:**

* **Name** (String): The name for the new Event.
* **OnStep** (Function): The function which triggers for every step of the Event's duration.
* **OnRandomEvent** (Function): The function triggered at random intervals defined by the randomEventChance field.
* **OnEnd** (Function): The function triggered at the end of the Event.

Each function passes the *Event strength multiplier* global variable as first argument

**Returns:**

Always returns the new Event.

#### **Event.find( Name )**

Finds an Event by its name.

**Parameters:**

* **Name** (String): The name of the Event to find.

**Returns:**

If the Event is found it returns the Event, nil otherwise.

#### **Event.findAll()**

Returns a table with all existing Events.

**Returns:**

A numerically indexed table of all Events.

#### **Event.getActive()**

Finds the currently active Event.

**Returns:**

If an Event is active, returns the Event, nil otherwise.

#### **Event.setActive( Event, [countdown], [duration] )**

Sets the active Event.

**Parameters:**

* **Event** (Event): The Event to trigger.
* **countdown** (Number): The countdown in frames before the Event starts. This will display the Alert.
* **duration** (Number): The duration of the Event in frames, setting this will bypass the duration set by the baseDuration and durationScaling fields.

## **DOT Types:**

### **Fields:**

* **particle** (ParticleType): When set, the DoT emits the given ParticleType as long as it’s active.
* **particleColor** (Color): The color blend of the ParticleType.
* **particleRate** (Number): A number from 1 to 100, determines how many particles are produced.
* **rate** (Number): The time in frames between each tic.
* **ignoreArmor** (Boolean): Whether the DoT’s damage is not reduced in relation to the actor’s armor stat. Defaults to false.
* **sound** (Sound): The sound played for each tic of the DoT.
* **(1.9.2+) showDamage** (Boolean): Determines whether damage numbers are displayed. Defaults to true.
* **damageColor** (Color): The color of the damage numbers created by the DoT.

### **Functions:**

#### **DOT.new( Name )**

Creates a new DoT type.

**Parameters:**

* Name (String): The internal name for the DoT type.

**Returns:**

Always returns the new DoT type.

#### **DOT.find( Name )**

Finds a DoT type by its name

**Parameters:**

* Name (String): The name of the DoT type to find.

**Returns:**

If the DoT type is found it returns the DoT type, nil otherwise.

#### **DOT.findAll()**

Finds all available DoT types.

**Returns:**

A numerically indexed table of all DoT types.

Note: Starstorm’s DoT types can be accessed by this method or by the following globals:

* DOT\_FIRE
* DOT\_POISON
* DOT\_CORROSION
* DOT\_BANE

#### **DOT.addToDamager( Damager, DotType, Damage, Tics, Index, [Stacks] )**

Applies a DoT type to a damager.

**Parameters:**

* Damager (DamagerInstance): The damager to apply the DoT type to.
* DotType (DoT type): The DoT type to apply on the damager.
* Damage (Number): The damage dealt by the DoT type each tic.
* Tics (Number): The amount of tics to do before the DoT type is removed.
* Index (String or Number): A custom DoT identificator. If a DoT is applied on an actor with an active DoT of the same type and index it will just increase the amount of tics to perform. If the DoT is applied to an actor with an active DoT of the same type but a different index it will apply as a separate instance, besides the existing one.
* Stacks (Boolean): (Optional) When set to true, if the DoT is applied to an actor with an active DoT of the same type, it will be stacked, regardless of the Index.

#### **DOT.addToActor( Actor, DotType, Damage, Tics, Index, [Stacks] )**

Applies a DoT type to an actor.

**Parameters:**

* Actor (ActorInstance): The actor to apply the DoT type to.
* DotType (DoT type): The DoT type to apply on the actor.
* Damage (Number): The damage dealt by the DoT type each tic.
* Tics (Number): The amount of tics to do before the DoT type is removed.
* Index (String or Number): A custom DoT identificator. If a DoT is applied on an actor with an active DoT of the same type and index it will just increase the amount of tics to perform. If the DoT is applied to an actor with an active DoT of the same type but a different index it will apply as a separate instance, besides the existing one.
* Stacks (Boolean): (Optional) When set to true, if the DoT is applied to an actor with an active DoT of the same type, it will be stacked, regardless of the Index.

#### **DOT.removeFromActor( Actor, DotType )**

Removes all instances of the passed DoT type on an actor.

**Parameters:**

* Actor (ActorInstance): The actor to remove the DoT type from.

* DotType (DoT type): The DoT type to remove from the actor.

#### **DOT.checkActor( Actor, DotType )**

Checks for instances of the DoT type on the passed actor.

**Parameters:**

* Actor (ActorInstance): The actor to check the DoT type from.

* DotType (DoT type): The DoT type to check on the actor.

**Returns:**

True if the DoT type is active on the actor, otherwise false.

#### **(Advanced) DOT.getActive( Actor )**

Finds all active DoTs in an actor.

**Parameters:**

* Actor (ActorInstance): The actor to check.

**Returns:**

A numerically indexed table of all active DoTs (Not DoT types, to get the DoT type, check the “dotType” field of each element of the table).