[Event mods] Part 2: Event Engine 0.4 documentation

Overview

Official documentation of the event engine of Planet Centauri.The event engine unlocks all features of the game’s engine that are not normally accessible to players. It allows to define new rules, create puzzles, riddles, challenges and even themed dungeons.The event system is defined through special icons in the world, invisible to the player, but with noticeable effects.

Introduction

The event engine unlocks all features of the game’s engine that are not normally accessible to players. It allows to define new rules, create puzzles, riddles, challenges and even themed dungeons.

The event system is defined through special icons in the world, invisible to the player, but with noticeable effects.

4 different categories exist:

• Simple [events]. These will trigger an action in the world, such as creating an item, destroying a block, spawning a monster, etc.
• Passive [triggers], which activate under specific conditions. For example, when the player enters a zone, kills a monster, opens a chest, etc. an activated trigger will send a signal to all linked events.
• Active [triggers], which are both triggers and events. The spawn trigger, for example, allows to spawn a monster as a event, and sends a signal to all linked events when the spawned monster(s) die as a trigger.
• Initialization triggers [initializers] which are active triggers that are activated automatically once at the world’s creation. It can be used for generating the content of a chest when the world is created or on room instanciation.

Testing examples

Each section will include testing examples. You don’t have to read nor fully understand everything to try those.

Each example will look like the following:

A testable encoded example (base64), e.g.:

… Followed by an image, to show the visual of the example in action.

Important: You must be in building mode to use the editing tools and commands.
NB: You can pick the building mode on the character creation screen.

Before importing an example, make sure that events are visible.
To do so, enter the following command (use the “Enter” key to access commands):

To hide events, use the following command:

1. Copy the base64 code
2. Put your cursor in a zone where you have enough free space (in the sky for example)
3. Enter the following command: /import_region

You should see the example room appear under your mouse cursor.

Examples being useful to show how to use each event, you will often need to activate those manually.
To do so, put your mouse cursor on an event (red block) then write in the command prompt:

For triggers (green blocks) with a specific activation, you will need to interact in-game to activate them (using /ev emit will not be useful in that case)

You can easily delete an example by holding the N key in the top left corner of the room, and then moving your cursor to the bottom right corner before releasing the key.

You will notice that the region remains there (The white outline is still visible).
To remove a region, use the following command:

• Events (red blocks) do not need a region to function. You can directly import those with the command : /import
• If you already have set a region, you can remove its content (blocks, events, decorations) and import another example without having to remove then recreate a new region, by using directly the /import command.
• You can share a creation on the forums in an encoded text format (base64). To do so you just have to copy it using the C key, which works the same way as deleting blocks with N. You then just need to paste the text (contained in the clipboard) with Ctrl+V between “code” tags.

Activation zone

An event is tied to an activation zone. You will be allowed to activate it only if the player is in the same zone.

There are 4 types of zones, in order :

• global
• world
• biome
• room

If the specified zone is “global”, the event will be activated whatever the position of the player is in the universe. This allows to build interdimensionnal events, like the serpent door which opens only when you have killed the dragon in another dimension.

If the specified zone is “world”, the event will be activated whatever the position of the player is in the world.

“biome” includes dungeons or entire biomes, which contain “rooms”.

Warning: the closest to “global” is the zone, the heavier the event will be (performance-wise), because events are saved in a partitioning system which allows to “sort” them by zone.
So, the smaller the zone is, the fewer events the game will need to process. You should greatly pick “room” and “biome” whenever it’s possible.

Nb:
> A dungeon requires only “room” and “biome” zones
> In a challenge zone, we only require “room” zones

In the json interface, we chose the activation zone through the “update” field :

Identification

An event is identified by a GUID (Global Unique Identifier). As its name suggest, each GUID must be unique. It allows to create links between events without causing ant collision.

A GUID has a {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format, ‘x’ being an hexadecimal number.
In the json interface, the GUID is defined by the “guid” field :

Activation

An event is activated by different ways, depending on the signal received :

• Default (blue)
• Reset (purple)
• Activate (cyan)
• Deactivate (red)

The most common signal is ‘Default’, which allows to activate the event’s behaviour.
Reset only works for specific events and allows it to set it back to zero.

An event can be activated or deactivated. In the second case, it will be greyed out and will stop working, even if it receives a ‘Default’ or ‘Reset’ event.
Activate/Deactivate allow to activate or deactivate an event.

To link a trigger to an event from the json interface, you need to add an “events” field, and specify a (event_guid, signal) couple list.

Ex:

Here, we link a “chrono” trigger to another event.
When the set 10 seconds of the timer will be over, it will then send a signal to the given event, which will then start working.

Using command lines

Important : Setting a “room” type event (for challenges) requires first to create a region.

Display/Hide events and regions:
/show events
/hide events

Recreate links between events (rarely used because adding an event refreshes all links automatically):

/ev relink

Create an event (requires the json of the event in the clipboard)
/ev add

Remove an event:
/ev rm

Copy an event (and placing the json in the clipboard):
/ev get

Cutan event (and placing the json in the clipboard):
/ev cut

Copy the GUID of the event under the mouse cursor:
/ev get guid

Modify the attributes (data and events) of the event (requires the json of the event in the clipboard) under the mouse cursor:
/ev set

Add a link to the event under the mouse cursor:
/ev link {GUID}
/ev link {GUID} signal

Link the trigger under the mouse cursor to all drigers in the region with a deactivation event (Allows to deactivate everything when the event/challenge is completed):
/ev link final

Link the trigger under the mouse cursor to all drigers in the region with a reset event(Allows to reset everything when the player leaves the region or fails a challenge for example):
/ev link reset

Clear all links on the trigger under the mouse cursor:
/ev link clear

Simulate a signal on an event under the mouse cursor:
/ev emit
/ev emit reset

Simulate a signal on an event with a specific GUID:
/ev emit {GUID}
/ev emit reset {GUID}

Create a region. Requires a border made with blocks [+] (pc_block_editor2) and placing the mouse cursor inside the region.
/region

Remove a region (Requires placing the mouse cursor inside the region):
/region remove

Export a room into the clipboard (Requires borders with blocks [+] and mouse inside the zone):
/export

Import a room from the clipboard, and add automatically the region and border blocks [+] (Be careful not to import the same events twice, so be sure to save beforehand):
/import_region

Import the content from the clipboard, without adding region or border:
/import

Export a room, but in a file to be shared or used later:
/export filename

Import a room from a file:
/import filename

Import a room from a file, and add the region and border blocks [+]:
/import filename region

Shortcuts

Event shortcuts with numeric pad:

0 : /ev clear => Remove links from selected event
1 : /ev get guid => Copy selected event’s GUID to the clipboard
2 : /ev link guid => Create a default link on selected event. Requires a GUID in the clipboard
3 : /ev link guid reset => Create a reset link on selected event. Requires a GUID in the clipboard

4 : /ev get
5 : /ev add
6 : /ev cut

Editing shortcuts with keyboard:

X: Cut a zone (hold)
C: Copy a zone (hold)
N: Delete a zone (hold)
V: Paste a copied zone

Hold, in two steps:
1. Hold input with mouse on the top left corner of the zone
2. Move mouse cursor to the bottom right corner of the zone, then release

“Cut” and “Copy” tools will place the structure into the clipboard in a text format you can keep, then allows to paste it back into the game, as if it was simple text.
You can then easily share structures from sites like pastebin[pastebin.com].

/! Be careful, pasting a structure with event in a zone without region will link them to the global region of the current biome. You need to set a region before pasting, else you will need to cut and paste all the events for them to work properly /!
=> It is important to keep a copy of your structure without events aside before adding events to it. This way, we paste the original version, add the region, and then we can copy/paste the version with event without trouble.

Event blocks [Red]

Here is the list of all event red blocks.
Reminder: An event is started by a trigger, but isn’t linked to any block itself.

Event: Block creation

Creates blocks from the position of the event when receiving a ‘Default’ signal, destroys them with a ‘Reset’ signal.

type: “create_blocks”
Parameters:

• “id” The id of the block(s) to create (found in assets/moddable/blocks/)
• “dx” et “dy” Relative position of the blocks to spawn from the event (integrer, in blocks)
• “wid” et “hei” The size (width and heigth) of the zone to create
• “forced” Sets whether or not we place the block if there is an entity behind it
• “probability” Does nothing for now

Ex:

Event: Block destruction

When receives a ‘Default’ signal, destroys blocks from the position of the event.

type: “destroy_blocks”
Parameters:

• “dx” et “dy” Relative position of the blocks to spawn from the event (integrer, in blocks)
• “wid” et “hei” The size (width and heigth) of the zone to destroy

Ex:

Event: Decoration creation

Creates decorations from the position of the event when receiving a ‘Default’ signal, destroys them with a ‘Reset’ signal.

type: “create_decorations”
paramètres:

• “id” The id of the block(s) to create (found in assets/moddable/blocks/)
• “dx” et “dy” Relative position of the blocks to spawn from the event (integrer, in blocks)
• “hrepeat” et “vrepeat” The amount of decorations to place with horizontal and vertical repetition.
• “hsep” et “vsep” The horizontal and vertical separation between each decoration
• “probability” Does nothing for now

Ex:

Event: Decoration destruction

Destroys decorations in a set area

type:”destroy_decorations”
Parameters:

• “dx” et “dy” Relative position of the blocks to spawn from the event (integrer, in blocks)
• “wid” et “hei” Define the size of the area
• “drop” Sets if whether of not destroyed decorations should drop on the ground
• “filters” If the list is empty, all decorations in the area will be destroyed, else only the listed ones will be affected.

Ex:

Event: Unlocking

Unlocks the locked decoration on the position of the event (ex: chest, door).

type: “unlock”

Ex:

Event: Sound play

Plays a sound

type: “play_sound”
paramètres:

• “id” The sound ID
• “spacialized” Sets if the sound should be played as spacialized (3d sound) or not (global sound)

Ex:

Blocs Trigger passif [Vert]

Here is the list of all passive triggers. Their only purpose is to trigger events.
It is useless to send a signal because they don’t have any other effect.

Trigger: Player detection

Emits a signal when the player enters the region.

type: “coming”

Ex:

Emits a signal when the player leaves the region.

type: “leave”

Ex:

Emits a signal when the player enters a set area.

type: “coming_zone”
Parameters:

• “dx1” “dy1” “dx2” “dy2” Relative coordinates in blocks of the rectangles that defines the zone.

Ex:

Trigger: View detection

Emits a signal when the view enters the zone.

type: “view_enter”

Ex:

Emits a signal once when the view leaves the zone.
Requires to be reset to be able to emit another signal.
Needs to be in the “world” update zone to work properly (Should be used with caution)

type: “view_leave”

Ex:

Trigger: Damage on player detection

Emits a signal when the player takes damage.

type: “get_damages”

Ex:

Trigger: Object opening

Emits a signal when the object on the position of the event is opened.
Allows to detect when a player opens a door or a chest.

type: “open”

Ex:

Active trigger blocks [Vert]

Here is the list of all active trigger blocks.
They behave as both triggers and events.
You can then send signals to trigger them.

Trigger: Monster spawning

When receiving a ‘Default’ signal, spawns a set amount of monsters.
A ‘Reset’ signal despawns all spawned monsters.
When all spawned monsters have been killed, emits a signal.
Linking several spawn triggers allows to create waves of monsters.

type: “spawn”
Parameters:

• “spawns” The list of monsters to spawn with the following attributes:
  • “attributes” Internal monster attributes with following parameters:
    • “id” The monster id (found in assets/moddable/monsters)
    • “level” The monster’s level
    • “level_min” et “level_max” The monster’s level, picked randomly between two values
    • “rarity” the monster’s rarity, with the following parameters:
      • “rarity” The rarity level of the monster (from 0 to 6)
      • “color” The monster’s color type (from 0 to 4)
    • “rarity_min” et “rarity_max” The rarity level of the monster, picked randomly between two values
    • “life” Monster’s health points
    • “life_min” et “life_max” Monster’s health points, picked randomly between two values
    • “effects” The list of permanent affixes of the monster (To set them manually):
      • “type” The affix type (See list below)
      • “level” The level of the affix (From 0 to 6)
      • “permanent” Sets whether or not the effect is permanent (1 by default)
  • “count” The amount of monsters spawned
  • “dx” et “dy” The relative position of the monsters
  • “probability” Probability to spawn monsters

List of effects:

• “giantbonus”
• “staminabonus”
• “lifebonus”
• “damagebonus”
• “elementaldamagebonus”
• “recoilprotect”
• “recoilbonus”
• “agility”
• “criticalbonus”
• “criticaldamagebonus”
• “staminaregeneration”
• “liferegeneration”
• “lifeperdeath”
• “staminaperdeath”
• “steallife”
• “stealstamina”
• “staminaperhit”
• “damagesreflect”
• “convertlifestamina”
• “convertstaminalife”
• “fireresistance”
• “iceresistance”
• “rockresistance”
• “thunderresistance”
• “lightresistance”
• “shadowresistance”
• “fireimmunity”
• “iceimmunity”
• “rockimmunity”
• “thunderimmunity”
• “lightimmunity”
• “shadowimmunity”
• “bluntresistance”
• “stabbingresistance”
• “cuttingresistance”
• “explosiveresistance”
• “physicaldamagereduction”
• “elementaldamagereduction”
• “burnresistance”
• “poisonresistance”
• “slowimmunity”
• “burnimmunity”
• “poisonimmunity”
• “frozenimmunity”
• “stoneimmunity”
• “haste”
• “slow”
• “gold”
• “ghost”
• “invisibility”
• “burned”
• “poisoned”
• “frozen”
• “stone”
• “stopregenlife”
• “torch”
• “toxic”
• “inflictslow”
• “inflictstopregenlife”
• “inflictstopregenstamina”
• “chickenperhit”
• “chickenarmor”
• “firemortar”
• “firedamagebonus”
• “icedamagebonus”
• “rockdamagebonus”
• “thunderdamagebonus”
• “lightdamagebonus”
• “shadowdamagebonus”
• “stabbingdamagebonus”
• “bluntdamagebonus”
• “cuttingdamagebonus”
• “explosiondamagebonus”
• “strongfocus”
• “savageboss”
• “unbalanced”

Ex:

Function: Challenge (visual)

Starts a challenges and its visual indications using an animation.
Triggers linked events once the animation is over.

Ex:

Function: Timer (visual)

Starts and displays a global timer when receiving a ‘Default’ signal.
Stops the displayed timer when receiving a ‘Reset’ signal.
Emits a signal when the timer reaches 0.
The timer being global, you can’t have more than once at a time, else the new one will overwrite the first. Because of this, it is impossible to chain global timers directly.

type: “chrono”
Parameters:

• “timer” In seconds (integrer)

Ex:

Function: Timer (local)

Works exactly like the global timer, but isn’t displayed and can have multiple instances at a time.
Uses a local timer which is invisible to the player. You can activate several local timers at the same time, while having an active global timer.

type: “chrono_local”
Parameters:

• “timer” in seconds (integrer)

Ex:

Alternate version if you need a more precise timer (float):

Function: Random

Allows to emit a signal depending on a set probability.

type: “dice”
Parameters:

• “p” A floating number from 0.0 (0%) to 1.0 (100%)

Ex:

Function: Switch

A switch is just a basic switch. If it’s activated and receives a signal, it sends it back to linked events.
Deactivating it allows to block all further incoming signals.

A switch allows to have an event that activates only once, like the butcher spawn in prisons, that doesn’t activate again once the corresponding butcher has been killed (Prevents from farming in prisons)
The state of a switch is saved when the player leaves the game.

type: “switch”

Ex:

Function: Counter

A counter starts from 0 and increments each time it receives a ‘Default’ signal. A ‘Reset’ signal sets it back to 0.
Once the set value has been reached, it emits a signal.
This time of trigger allows to acivate some events only once, or when a certain amount of actions have been accomplished.
It is kind of a more powerful version of the switch.

type: “counter”
Parameters:

• “emit_at” An integrer superior to 0 sets the value from which it will emit a signal.

Ex:

Function: Hub

Allows to send the received signal to each linked event, with the possibility to alter the signal.

Uses two additional special signals:

• “pipe” Which will emit the same signal the hub received (white color)
• “pipe_inv” Which will emit the opposite signal the hub received (grey color)

A signal X is sent to the hub.
If Y is of type “pype”, then emits X
If Y is of type “pype_inv”, then emits the opposite of X, according to the following table:

type: “hub”

Ex:

Function: Dispatcher

Allows to send the received signal to each of the linked events, one by one.

type: “dispatch”
Parameters:

• “count” The amount of linked events
• “state” The actual event index to send the next signal
• “loop” Sets if the dispatcher should start over once the last signal has been sent (1 by default)

1. A signal X is sent to the dispatcher
2. The counter is incremented and we send the signal X to the event N-1 (N being the counter) if the corresponding event exists
3. If N-1 equals “count” (the amount of linked events), either it is set back to 0 if “loop” is equal to 1, or nothing happens.

Ex:

An alternative version of the dispatcher, “timed_dispatch” works the same way, except that once a default signal has been received, it activates itself periodically thanks to an internal timer.

type: “timed_dispatch”
Parameters:

• “timer” The duration of the timer between each activation
• “is_running” Indicates if whether or not the event is running

Ex:

Initializer blocks [Blue]

Here is the list of initializers below:
Those work exactly like triggers, except that they are called once on world’s creation or room instantiation.

Initializer: Generating items in a chest

Allows to generate the content of a chest when creating the room. You can also tell if the chest must be locked or not.
Can also be used like an event, and must be placed on the desired chest.

type: “generate_items”
Parameters:

• “chest_drops” A list of chest drops that includes the following parameters:
  • “ind” The chest drop id to spawn (found in assets/moddable/chestdrops)
  • “min” The minimum amount of items to generate
  • “max” The maximum amount of items to generate
• “random_drops” A list of drops, that will allow to generate the content of the chest semi-manually. A drop has the following parameters:
  • “ind” The item index
  • “percent” la probabilité de générer l’item
  • “min” le minimum de la stack générée
  • “max” le maximum de la stack (choix aléatoire d’une valeur entre min et max)
• “manual_drops” un liste de drops a générer. Un drop manuel étant constitué des paramètres suivants:
  • “ind” The id of the item (assets/moddable/drops)
  • “count” The amount of items dropped for this id
• “lock” Sets if whether or not the chest should be locked (Can’t be opened manually)
• “clear” Sets if whether or not the content of the chest should be cleared before generating the drops
• “dx” et “dy” The relative position of the chest from the event

Ex 1:

Ex 2: