Differences

This shows you the differences between two versions of the page.

--- ixe:features:custom:apexevolution [2025/03/07 06:56] – created qople
+++ ixe:features:custom:apexevolution [2025/03/07 20:46] (current) – [Shot System] Added shot system documentation. qople
@@ Line 505: / Line 505: @@
 AEV contains a robust event-based shot system that can efficiently handle hundreds of shots at a time. In version 1.0 it is hard-coded to only apply to the cannon, rocket, bertha, and sentrygun, but an update is planned soon to let mapmakers register new modules to use this feature.
-TODO: Shot behavior documentation here.
+==== Overview ====
+Each shot type in AEV consists of:
+  * A base shot class, such as "cannon" or "rocket", that determines the basic behavior of the shot.
+  * A module name that stats for the shot are pulled from automatically. The proper variables must be defined on the module for the shot to work properly.
+  * A series of behaviors that modify the shot, each made of a name, a trigger, and a function to run when that trigger happens.
+==== Shot Classes ====
+Currently, only two types of shots are supported: cannon and rocket. Each has a set of variables that must be defined on them for the shot, or for most behaviors, to work properly. These values will be automatically updated in the shot system when changed __by an upgrade__. If an external source changes a stat value used by the shot system, it must be manually updated by calling the message "StatsUpdated" with data being a list of: [module name, stat name, new value].
+=== cannon ===
+A cannon shot has the following base logic, without behaviors:
+  * Creates a shot (or several) in the direction the unit creating the shot is facing.
+  * Each shot moves in a straight line until it hits a wall or leaves the map, then destroys itself.
+This logic can be added onto with behaviors, to do things like "destroy the shot when it hits creeper" or "damage creeper when the shot is destroyed". More on behaviors below.
+The following variables must be defined on a module that creates a cannon shot:
+<tabbox num_shots>
+The number of shots created with each call to the "CreateShot" message.
+<tabbox spread>
+The spread in degrees between each shot. Total spread of the volley is always numShots * spread.
+<tabbox spead_rand_mode>
+If set to 0, shot spread is uniform. If set to 1, shot angle is random over the area of the volley. Total spread still scales with num_shots with random spread mode on, spread between bullets is just made random.
+<tabbox shot_speed>
+The distance each shot moves at, in cells per frame.
+<tabbox shot_gravity>
+The force of gravity on each shot, in cells per frame squared.
+<tabbox shot_damage>
+The damage done or AC depth deposited by the shot. Used by damage and ac behaviors.
+<tabbox shot_damage_distance>
+The radius of damage done or AC deposited by the shot. Used by damage and ac behaviors.
+<tabbox shot_damage_count>
+The maximum number of cells that can be damaged by damage behaviors. Used exclusively by damage behaviors.
+</tabbox>
+=== rocket ===
+Rocket shots have the following base logic, with no behaviors:
+  * One or more shots are made, targeting deepest creeper in range of the unit creating the shot using the module's RA range.
+  * The shot follows a path to the target using GetRaPath.
+  * When it reaches the end of the path, the shot destroys itself.
+This logic can be added onto with behaviors, to do things like "destroy the shot when it hits creeper" or "damage creeper when the shot is destroyed". More on behaviors below.
+The following variables must be defined on a module that creates a cannon shot:
+<tabbox num_shots>
+The number of shots created with each call to the "CreateShot" message.
+<tabbox target_rand>
+The radius of a square (so side length is 2 * target_rand) that a random offset is added to the target location. Helps reduce many shots targeting the same cell. 0 means no offset is used.
+<tabbox shot_speed>
+The distance each shot moves at, in cells per frame.
+<tabbox shot_damage>
+The damage done or AC depth deposited by the shot. Used by damage and ac behaviors.
+<tabbox shot_damage_distance>
+The radius of damage done or AC deposited by the shot. Used by damage and ac behaviors.
+<tabbox shot_damage_count>
+The maximum number of cells that can be damaged by damage behaviors. Used exclusively by damage behaviors.
+</tabbox>
+==== Behaviors ====
+Shot behaviors are at the core of the AEV shot system. They allow every shot to be modified in complex ways, using declarative syntax without sacrificing on efficiency. Each behavior consists of a reference name used to delete the behavior later, a trigger, and a function and arguments to call when that trigger happens.
+The basic syntax of a behavior is as follows:
+<code>
+"name/trigger/function/arg1/arg2/..."
+</code>
+Many behavior functions have arguments, but not all are required. As an example, this is a behavior on the cannon:
+<code>
+"basehit/hitcreeper/destroy"
+</code>
+This is a behavior with a reference name of "basehit," that activates on the shot hitting creeper, and destroys the shot when activated. (There is a separate behavior for damaging creeper on destroy.)
+=== Reference Name ===
+The reference name of a behavior can be anything, and doesn't even have to be unique. It is only used by the "RemoveBehavior" upgrade effect to remove it if needed, and is mostly used to disable the starting behaviors when weapon artifacts are collected.
+=== Triggers ===
+A trigger is simply an event that can happen over the course of a shot's lifetime. If and when it happens, if there are any behaviors on a shot associated with that trigger, the behaviors' associated functions are called.
+The current triggers supported by the shot system are:
+<tabbox create>
+Called when the shot is first created.
+<tabbox ondestroy>
+Called when the shot is destroyed.
+<tabbox hitcreeper>
+Called on the frame where the shot first contacts creeper (not anticreeper).
+<tabbox frametravel>
+Called once every frame while the shot exists, after the shot moves but before it checks for the hitcreeper trigger.
+<tabbox celltravel>
+Called once for every cell the shot travels through. Called more often each frame depending on the speed of the shot.
+</tabbox>
+=== Functions ===
+A behavior's function is the action that is performed when the trigger happens on its shot. Most can accept arguments that can further customize their effects.
+Currently suported behaviors are:
+<tabbox damage>
+Runs a DamageCreeper function at the shot's current position, using the module's "shot_damage", "shot_damage_distance", and "shot_damage_count" vars as the inputs.
+Optional arguments are: multiplier to damage, multiplier to distance, and multiplier to count, in order. All default to 1 if not listed.
+<tabbox ac>
+Adds anticreeper in range at the shot's position. Uses the module's "shot_damage" and "shot_damage_distance" variables.
+Optional arguments are: multiplier to damage, and multiplier to distance. Both default to 0 if not given.
+<tabbox destroy>
+Destroys the shot, calling all behaviors attached to the ondestroy trigger.
+Optional argument is whether to call the walkback behavior before detonation on cannon shots. Defaults to true.
+<tabbox walkback>
+Cannon class shots only.
+Attempts to "walk back" the shot to the last cell there was no creeper on. Checks every cell up to one frame back in time. When used the frame the shot hits creeper, this lines up the shot with the edge of the creeper pool, preventing shots from hitting random small distances into the creeper instead of at the visual edge.
+No arguments.
+<tabbox afterdelay>
+Triggers a second behavior after a certain amount of time, several times with a delay in between, or both.
+Arguments are the initial delay in frames, the number of activations, the delay between successive activations, and then the function to activate each time, followed by any arguments for that function.
+For instance, the behavior "example/hitcreeper/afterdelay/20/1/0/destroy/4" will run the "destroy" function once, 20 frames after the shot first hits creeper.
+Any behavior run after a delay will use the position of the shot **after the delay has elapsed**, not when the afterdelay timer was started. If the shot was destroyed in that time, it will use the position the shot was destroyed at.
+</tabbox>
+All these behaviors can be combined and added together to produce many of the effects seen in weapon artifacts like piercing shots on the cannon, the AC trail on the maker, or the delayed detonation on the rocket, just with an AddBehavior effect or two.
+==== Making Your Own Shot Types ====
+To be added in a future update. For now, this only applies to the cannon, sentrygun, rocket, and bertha.

Knuckle Cracker Wiki

User Tools

Site Tools

Differences

Page Tools