Combat System

Functions relating to the combat system. You can start and stop fights, and manipulate and inspect their state.

Basics

The basic flow is that you create a new session using the Combat2 function, add some participants, and then start it with the Begin method.

A newly created session does not contain any participants at all, not even the player character (whom you can add with the global variable Player). You could, if you want to, forego adding the player to a combat session, and have only AI-controlled participants fight it out.

NPC participants can be created by using the Creature function, described in the Constructors section.

Combat2

• (Combat Session) - a new, empty combat session.

Creates and returns a new Combat Session. You can call the other combat functions on this object.

GetActiveCombat

• (Combat Session) - active combat, or nil if there is none

Returns the Combat Session that is currently in progress, e.g. while a combat callback is running. If there is no active combat, returns nil. Useful if you need access to the combat such as from within an Item Use Script.

combat:

AddParticipant

participant

• participant (Creature) - the new creature to involve in this fight.

Adds a new participant to the combat session. All participants must be added before calling Begin.

combat:

Begin

Begins a combat session. If the same combat session had been started and stopped previously, it will resume where it left off. The running script is paused until combat completes or pauses.

combat:

End

Manually stops a combat session. Any pending XP will be awarded to the player, and the script that originally called Begin will be resumed. You don't need to call this unless you want to stop the fight mid-way through.

combat.

Round

• number - read-only

The current round number. Starts at 1, and increments after all participants have performed an action.

Participant State

Use these functions to force characters into specific states, or to inspect their current state. This is useful to, for example, force a character to already be swallowed by some predator before the combat starts.

Note that each Combat Session is completely separate and self-contained. A participant could, for example, be grappling with another participant in one session, and be swallowed by that same creature in another session. In other words, combat-related states like grappling, swallowing, stunning and the like are 'forgotten' as soon as the combat session ends. It is up to your scene scripts to figure out how participants have interacted with each other, so that the scene can respond to the combat's outcome appropriately.

caution

Be sure that all Creatures you pass to these functions, are already registered to this combat session using AddParticipant. If this is not done, the functions will raise an error.

combat:

ApplyBuff

participant

buff

• participant (Creature) - the character to apply the buff to
• buff (PendingBuff) - the new buff to apply

Applies a temporary effect to a participant (may be the Player or an NPC). Refer to the 'Constructors' > 'Buffs' section for functions that create PendingBuffs.

combat:

IsGrappling

participant

• participant (Creature) - the character to check

• (boolean) - true if grappling, false otherwise

Returns true if this Creature is currently grappling with anyone.

combat:

IsSwallowed

participant

• participant (Creature) - the character to check

• (boolean) - true if swallowed, false otherwise

Returns true if this Creature has been swallowed by anyone.

combat:

IsGrappleInitiator

participant

• participant (Creature) - the character to check

• (boolean) - true if grappling and initiator, false otherwise

Returns true if this Creature is the one 'on top' in a grapple, i.e. able to release or swallow the target. If the participant is being grappled, or is not grappling, returns false.

combat:

GetPredator

participant

• participant (Creature) - the character to check

• (Creature) - the predator who swallowed the input participant, or nil

Returns the Creature who swallowed the specified prey Creature. If the prey Creature is not swallowed, returns nil.

combat:

GetGrapplingWith

participant

• participant (Creature) - the character to check

• (Creature) - the grapple partner, or nil

Returns the grappling partner of a Creature. If the input participant is not grappling, returns nil.

combat:

SetVored

predator

prey

• predator (Creature) - the predator swallowing the prey
• prey (Creature) - the prey being swallowed

Forces the two specified participants to enter into a vore state, such that the prey is swallowed by the predator. If either participant is already grappling or swallowed, they must first exit these states before this function is used; not doing so may cause the game to malfunction.

combat:

UnsetVored

predator

prey

• predator (Creature) - the predator swallowing the prey
• prey (Creature) - the prey being swallowed

Forces the two specified participants to cancel their vore status, such that the prey is released and the predator is no longer swallowing them.

combat:

SetGrappling

instigator

target

• instigator (Creature) - the grappling initiator
• target (Creature) - the target being grappled

Forces the two specified participants to enter into a grapple. The instigator will be 'on top', i.e. able to release or swallow the target. If either participant is already grappling or swallowed, they must first exit these states before this function is used; not doing so may cause the game to malfunction.

combat:

UnsetGrappling

a

b

• a (Creature) - the first grappling partner
• b (Creature) - the second grappling partner

Forces the two specified participants to stop grappling. The order of a and b does not matter, as long as the two Creatures are indeed grappling together.

Callbacks

You can use these functions to have the combat system inform you of certain events. For example, you can have a snippet of Lua code run every time a round ends, or whenever someone is swallowed by a predator. This is useful for scripting combat sequences beyond what the vanilla combat system normally allows.

combat:

OnRoundStart

callback

• callback (function(round)) - user callback function

Invokes the specified function when a combat round begins, before combat end logic, user input or AI actions are evaluated. The round parameter passed to the function is the number of the round that just ended (starting at 1).

combat:

OnRoundEnd

callback

• callback (function(round)) - user callback function

Invokes the specified function when a combat round ends, after the last participant has acted. The round parameter passed to the function is the number of the round that just ended (starting at 1).

combat:

OnCombatEnd

callback

• callback (function) - user callback function

Invokes the specified function when the combat ends. The callback has no arguments.

combat:

OnCreatureKilled

callback

• callback (function(killer, victim)) - user callback function

Invokes the specified function when a non-player participant dies, regardless of the type of damage that was last dealt. The killer and the victim are passed as arguments to the callback.

combat:

OnCreatureVored

callback

• callback (function(predator, prey)) - user callback function

Invokes the specified function when any participant is swallowed. The predator and prey are passed as arguments to the callback.

combat:

OnCreatureReleased

callback

• callback (function(predator, prey)) - user callback function

Invokes the specified function when any participant is regurgitated by their predator. The predator and prey are passed as arguments to the callback. This callback runs when a script uses the UnsetVored function, or when a predator is killed and their prey is released.

combat:

OnPlayerKilled

callback

• callback (function(killer, victim)) - user callback function

Invokes the specified function when the player character dies, regardless of the type of damage that was last dealt. The killer and the player are passed as arguments to the callback. Note that if the callback changes the player's Health to a non-zero value (i.e. 'resurrecting' the player), combat will resume as if nothing happened.