ASH Authoring Reference

Local, source-audited reference for the current ASH RPG Maker MZ battle stack.

Current audited plugins

How to use this site

Pick the RPG Maker database tab you are currently editing from the left. Tags are repeated in every tab where they apply. Skill and Item include the full current sequence-command table so you do not need to cross-reference another section.

Actor Tab

<ASH Battler Sheet: Holder4x14>

<ASH Pose Set: ArenBattle>

<ASH Pose Alias: attack, dagger_slash>

<ASH Positionals>\nfront: 1\nback: 2\nleft: 3\nright: 4\n</ASH Positionals>

Class Tab

<ASH Battler Sheet: Holder4x14>

<ASH Pose Set: RoguePoses>

<ASH Pose Alias: attack, rogue_attack>

Weapon Tab

<ASH Pose Set: DualDaggerPoses>

<ASH Pose Alias: attack, twin_dagger_attack>

<ASH Attack Skill: Twin Fang>

<ASH Battler Image: ArenTwinDaggers>

<ASH Battler Sheet: Holder4x14>

<ASH Behind Sheet: Cape_Back>

<ASH Above Sheet: Sword_Front>

<ASH Attachment: IronSword, 50, Holder4x14>

Armor Tab

<ASH Pose Set: HeavyArmorPoses>

<ASH Pose Alias: damage, heavy_stagger>

<ASH Battler Image: ArenHeavyArmor>

<ASH Battler Sheet: Holder4x14>

<ASH Behind Sheet: HeavyCape>

<ASH Above Sheet: Helmet_Front>

<ASH Attachment: ShoulderGlow, 75>

Enemy Tab

<ASH Battler Image: GoblinHolder>

<ASH Battler Sheet: Holder4x14>

<ASH Pose Set: GoblinPoses>

<ASH Pose Alias: attack, goblin_stab>

<ASH Positionals>\nfront: 1\nback: 2\nleft: 3\nright: 4\n</ASH Positionals>

Skill Tab

<ASH Action Execution>\npose: user, attack\nanimation: skill\ndamage: true\n</ASH Action Execution>

<ASH Sequence: Impact>\nanimation: skill\ndamage: true\n</ASH Sequence>

<ASH Range: 180>

All supported sequence calls

Valid inside <ASH Action Execution>, local <ASH Sequence: Name> blocks, and global preset bodies.

<ASH Sequence: Impact>
animation: skill
damage: true
</ASH Sequence>

<ASH Action Execution>
include: Impact
</ASH Action Execution>

Item Tab

<ASH Action Execution>\nhp: target, +500\nxpopup: target, "Recovered!"\n</ASH Action Execution>

<ASH Sequence: PotionEffect>\nhp: target, +500\n</ASH Sequence>

<ASH Range: 250>

All supported sequence calls

Valid inside <ASH Action Execution>, local <ASH Sequence: Name> blocks, and global preset bodies.

<ASH Sequence: Impact>
animation: skill
damage: true
</ASH Sequence>

<ASH Action Execution>
include: Impact
</ASH Action Execution>

State Tab

Targets & Values

Target selectors

Target preview highlight lifetime

RPG Maker's battler selection flash is used only while choosing a target. ASH explicitly clears preview selection when the player confirms a target and again at action start as a fail-safe. Movement-only and Jump-only actions therefore do not make the target blink during execution.

Target-plan directives

target_scope: currently normalizes scopes including self, ally, opponent, actor, enemy, and any. target_count: supports plans such as one and all. target_area: is reserved for registered free-position/spatial providers; ASH does not fake a grid.

Numeric Value Resolver

XPopup content

xpopup: target, "Poisoned!"
xpopup: target, variable:7
xpopup: target, state_name:4
xpopup: target, name:target
xpopup: target, formula:a.atk * 2
xpopup: target, eval:b.name() + " is stunned!"

Movement modes currently handled

movement: moveTo, x, y
movement: moveBy, x, y
movement: approach
movement: retreat, 100
movement: setHome
movement: commitOrigin
movement: return

Projectile sockets

Projectile endpoints use battler/socket notation. Built-in pose sockets include center, head, and feet, with custom sockets available through Pose preset data.

projectile: user.hand_r, target.center, Arrow, 24
projectile_arc: 48
projectile_rotate: true
projectile_scale: 1

Plugin Commands

These are RPG Maker Plugin Commands, not Notes-box tags.

Preset resolution

1. Local <ASH Sequence: Name> in the current Skill/Item.
2. Global SequencePresetManager preset.

Preset bodies contain ASH sequence commands only and should not include the Action Execution wrapper.

Movement & Home

Free-coordinate battler movement, speed/duration timing, optional Stamina, Current Home vs Original Home, and automatic pose ownership.

Movement aliases

Critical rule: approach is not an attack command

move: approach
target: target
duration: 60

This is movement only. It does not automatically request the database animation, apply damage, or declare an attack.

If a later mechanical offensive step exists, such as damage:, impact:, or projectile impact damage, a successful automatic approach may transition from its movement pose into semantic attack before that later offensive step. If an explicit pose: appears first, the explicit pose wins.

Default automatic pose behavior

Jump movement

jump: is a real free-coordinate movement primitive. Mechanical X/Y travels on the battlefield ground plane while a separate visual airborne height creates a parabolic arc.

jump: moveTo
x: 500
y: 300
duration: 60
height: 120

jump: moveBy
x: -200
y: 50
duration: 45
height: 80

jump: toward
target: target
distance: 50
duration: 60
height: 100

jump: retreat
target: target
distance: 200
duration: 60
height: 100

jump: home
duration: 60
height: 100

Defaults: Jump Height 96px, Jump Duration 30 game frames. Jump itself does not request an attack pose, database animation, impact, or damage. Add an explicit pose: if desired. Movement Stamina remains opt-in with stamina: true.

Float

float: set
height: 120
duration: 60

float: up
height: 80
duration: 30

float: down
height: 50
duration: 30

float: ground
duration: 60

wait_float:
# alias
waitfloat:

Float is persistent visual height. Mechanical X/Y does not change. Jump and Float heights add together visually.

Knockback / Pull

knockback: target, 200
origin: user
duration: 60

pull: target, 100
origin: user
duration: 45

Knockback moves targets away from the origin. Pull moves targets toward it without overshooting. Both use the normal free-coordinate Movement engine and battlefield bounds.

Jump interruption

interrupt: replace
interrupt: ignore
interrupt: queue

replace remains the default. It now preserves the current airborne visual height instead of snapping to zero before the replacement arc. ignore rejects the new request. queue starts it after the active jump lands.

Projectile routing & lifecycle

projectile: user.center, target.center, debug, 30
id: chain1
route: random_unique
bounces: 3

Routes: none, random_unique, random, nearest, return.

projectile_route: random
id: chain1

projectile_stop: chain1
projectile_resume: chain1
projectile_remove: chain1
projectile_reset_visited: chain1

A live route change affects the next segment of the same projectile. random_unique remembers visited targets. return sends the visual back to its source; self-damage on return defaults off.

Projectile geometric routing

Next target behind current target

projectile: user.center, target.center, debug, 45
id: pierce1
route: next_behind
bounces: 2
behind_angle: 60

next_behind uses the projectile's incoming direction. From the current target, ASH searches farther along that direction and chooses the nearest eligible battler inside the allowed cone.

behind_angle: is the allowed half-angle in degrees. A smaller number requires a straighter continuation. behind_max_lateral: can additionally limit sideways distance from the incoming route line.

Behind-route coordinate space

next_behind geometry is evaluated using the same live battler socket/render coordinates used by projectile travel endpoints. This keeps the geometric decision aligned with what the player actually sees on screen. Mechanical battlefield coordinates are used only as a fallback.

behind_max_lateral default: if omitted or left blank, lateral distance is unlimited. An explicit 0 is valid and means the next target must lie exactly on the incoming route line.

First → behind → first

projectile: user.center, target.center, debug, 45
id: ricochet1
route: behind_return_first
bounces: 2
behind_angle: 60

This compound route hits the originally selected first target, finds the nearest valid target behind it, then sends the same projectile back to the original first target.

Automatic projectile route transitions

projectile: user.center, target.center, debug, 45
id: chaos_chain
route: random_unique
route_when: all_hit
route_then: random
bounces: 10

The controller begins in random_unique. Once every eligible opponent has been visited, the same live projectile automatically changes to random and may begin repeating targets.

route_when: all_hit
route_when: hits:4

The route transition occurs after the current impact and before the next destination is selected.

Return is terminal: once a projectile using return reaches its original source, the projectile ends immediately even if its bounce count is still above zero. This is true for initial return routes, live route changes, and automatic transitions into return.

Spatial target areas

ASH target areas now operate in continuous battle-screen coordinates using battler sprite hitboxes rather than a grid.

Circle

target_area: circle
origin: target
radius: 160
debug: true
debug_frames: 120

Ring / donut

target_area: ring
origin: target
inner_radius: 80
radius: 220

Rectangle

target_area: rect
origin: target
width: 260
height: 120
rotation: 25

Cone

target_area: cone
origin: user
direction: target
range: 320
angle: 60

Line / beam

target_area: line
origin: user
direction: target
range: 500
width: 64

Origin and direction

origin: may use selectors such as user, target, allies (first resolved battler), or a point selector. Explicit x:/y: overrides selector origin.

direction: accepts a selector, point selector, numeric degrees, or left/right/up/down.

Hitboxes

Area collision uses each battler's live sprite bounds. hitbox_padding: expands those bounds for authoring/tuning.

Debug visualization

debug: true
debug_frames: 120

The area is drawn in cyan. Candidate hitboxes are red; affected hitboxes are green.

Spatial scope visibility

A spatial ability can display its actual target-area shape while selecting a target and/or again when that target-area step executes.

Selector preview

Spatial abilities default to showing their own actual scope during selection. A cone skill shows its cone; a circle skill shows its circle; a line skill shows its line. Other scope types are not shown.

scope_show_selector: true
scope_show_selector: false

Execution visibility

Execution scope display defaults off. Turn it on for telegraphs, deliberate presentation, or testing:

scope_show_execution: true
scope_show_execution: false

General shortcut

scope_show: true
scope_hide: true

debug: true also shows the execution scope and battler hitboxes.

Defaults

selector scope = shown
execution scope = hidden
debug:true = execution shown + hitboxes

Image Scope

target_area: image uses the alpha channel of a transparent image as an arbitrary target shape.

target_area: image
origin: target
image: ASH_TestCross
image_folder: img/ash_scopes/
image_width: 320
image_height: 160
image_rotation: 0
alpha_threshold: 16
scope_show_selector: true
scope_show_execution: true

Transparent pixels do not hit. Pixels whose alpha is at or above alpha_threshold are active. Collision samples across each battler hitbox rather than checking only its center.

Image controls

image:
image_folder:
image_width:
image_height:
image_scale:
image_scale_x:
image_scale_y:
image_rotation:
alpha_threshold:
image_anchor_x:
image_anchor_y:

Default folder: img/ash_scopes/. Default anchor is centered at 0.5, 0.5.

Custom battler hitbox notes

Actor and Enemy database notes may override automatic sprite bounds:

<ASH Hitbox>
width: 64
height: 96
offset_x: 0
offset_y: -12
padding: 0
</ASH Hitbox>

If no ASH Hitbox note exists, the live sprite bounds continue to be used automatically.

Custom battler hitbox anchors

Custom <ASH Hitbox> profiles use stable ASH battler/socket coordinates rather than sprite bounds.

<ASH Hitbox>
width: 44
height: 72
anchor: feet
offset_x: 0
offset_y: 0
padding: 0
</ASH Hitbox>

Anchors

anchor: feet
anchor: center
anchor: head

feet is the default. The box grows upward from the battler's stable ground/feet point. center centers the box on the stable battler center. head grows downward from a head/top socket when available.

offset_x and offset_y are local adjustments from the selected stable anchor. Identical battler instances therefore receive the same relative hitbox regardless of pose/frame.

When no custom ASH Hitbox note exists, automatic hitboxes continue to use live sprite bounds.

Timing

movement: moveBy
x: -400
y: 0
speed: 10

movement: moveBy
x: 400
y: 0
duration: 60

speed: is travel rate: farther movement naturally takes longer. duration: is an explicit travel-time override: different distances can be forced to take the same number of frames.

Stamina is opt-in per movement

movement: approach
target: target
distance: 100
speed: 10
stamina: true

Without stamina: true, movement ignores Stamina. If enabled and insufficient, the Stamina plugin may partially limit or deny travel. Approach defaults to breaking the remaining sequence on incomplete Stamina movement unless the authored failure policy says to continue.

Home

Ordinary movement never updates Home. Only setHome/updateHome/commitOrigin changes Current Home. Original Home remains the battle-start/configured formation anchor.

movement: setHome

movement: home
speed: 10

movement: originalHome
speed: 10

Pose System

Poses are semantic visual requests. Movement remains mechanical position; a pose never silently becomes combat logic.

Explicit sequence syntax

pose: user, attack
pose: target, damage
pose: user, guard

pose: can request either a semantic pose name or a concrete custom pose name. Concrete names bypass contextual semantic-variant replacement.

Built-in semantic pose names

idle, wait, ready
attack, guard
skill, spell, item
damage, evade, dead
victory, escape
move, walk, run, advance, retreat
thrust, swing, missile

Plugin Manager Additional Semantic Poses can register more names so contextual rules can treat them as semantic requests.

Resolution precedence

For semantic requests, contextual variant rules can win first. Current contextual condition precedence is:

runtime visual profile
→ state
→ weapon
→ armor
→ any equipment
→ enemy / actor identity
→ equipment/class/actor/enemy note aliases
→ Pose Set aliases / fallback

Within equally ranked contextual rules, rule priority breaks ties. Equipment preserves actual equip-slot order where relevant.

Note-tag aliases

<ASH Pose Alias: attack, dagger_slash>
<ASH Pose Alias: walk, wounded_walk>

Actor, Class, Enemy, Weapon, and Armor sources can map semantic names to concrete poses. Equipment aliases have precedence before Class/Actor aliases.

Stock RPG Maker MZ actor behavior

Native MZ motions supported directly by the renderer are:

walk, wait, chant, guard, damage, evade,
thrust, swing, missile, skill, spell, item,
escape, victory, dying, abnormal, sleep, dead

Semantic attack is special: ASH resolves the actor's equipped weapon attack motion to thrust, swing, or missile, and can request the normal weapon image. Unsupported concrete/native names fall back visually to MZ wait.

The built-in MZ Pose Set aliases idle → wait, hurt/hit → damage, defend → guard, casting → chant, cast → spell, and normal_attack → attack.

Built-in Holder/custom-grid defaults

The built-in Holder-style Pose Set contains concrete poses:

idle, guard, abnormal, damage, attack, item,
skill, magic, advance, escape, victory, enter, dead

Important built-in aliases include:

wait / ready → idle
defend → guard
hurt / hit → damage
normal_attack / attack1 → attack
attack2 → item
attack3 → skill
spell / chant / casting → magic
walk / run → advance
retreat → escape
attack4 → victory
entry → enter
death → dead

Editable built-in presets

The Plugin Manager now exposes all built-in Battle Poses presets as normal editable default entries instead of hiding them only in code.

Sheet Presets:
mz_actor
holder_4x14
static_battler
custom_grid

Pose Sets:
holder_default
mz_default
static_default

Runtime Visual Profiles:
mz_actor_default
static_battler_default

Editing an entry while keeping its built-in name overrides the hard-coded fallback of the same name. Pose Sets also expose explicit Semantic Alias Mappings, so mappings such as walk → advance or idle → wait can be edited directly.

Sheet-wide visual X/Y offset

Battler Sheet Presets expose Visual Offset X and Visual Offset Y. These are visual-only alignment corrections applied to every pose that uses the sheet.

Visual Offset X: 0
Visual Offset Y: 12

Positive Y moves the rendered battler body downward. Mechanical battlefield X/Y, Current Home, Original Home, Movement distance, and Stamina calculations are unchanged.

The offset is also applied to synchronized equipment attachment sheets. Projectile sockets follow the corrected rendered transform, so visual socket positions move with the body.

The built-in editable holder_4x14 sheet preset defaults to Visual Offset X: 0 and Visual Offset Y: 12.

Battler Y-depth grouping

Actors and enemies sort as whole visual groups using the battler container's mechanical battlefield Y. Greater Y renders in front of smaller Y.

An actor's body and all ASH equipment attachments remain together during battlefield sorting. Internal attachment layers are preserved: negative layers stay behind the body, the body remains layer 0, and positive layers stay above it. Another battler cannot render between the body and its weapon/cape/armor attachment.

Sheet-wide Visual Offset Y does not alter depth sorting; the mechanical ground Y remains authoritative.

Pose completion

Custom-grid pose definitions control looping, ping-pong, hold-last-frame, and ReturnPose. A non-looping pose commonly returns to idle; looping poses such as movement/idle remain active until another request interrupts them.

wait_pose:, wait_pose_event:, freeze_frame:, and release_frame: provide synchronization/control without changing mechanical position or targets.

Stamina

General battle resource. Current Stamina may exceed the normal max; movement integration is opt-in per movement instruction.

Default Max Stamina: 100
Turn Recovery Mode: Full Refill
Movement Uses Stamina: true
Movement - Pixels Per Unit: 2
Movement - Stamina Per Unit: 1

Note tags

<ASH Max Stamina: 120>
<ASH Stamina Plus: 20>
<ASH Stamina Rate: 125>

Sequence calls

stamina: user, -10
stamina: user, +10
stamina: user, 25%
stamina: user, full

stamina_set: user, 50
stamina_set: user, 10000

stamina_cost: user, 15

Current Stamina is uncapped above maxStamina(); max remains the normal battle-start/full-refill reference. Movement cost is based on actual distance only. Speed and duration do not change Stamina cost.

Implicit database animation timing

If an ASH sequence has no explicit animation: command, ASH preserves the skill's normal database animation but requests it at action start as a non-blocking presentation effect. RPG Maker's later automatic call is suppressed only as a duplicate.

animation: skill
animationTarget: target

If an explicit animation command exists, that ASH step owns animation timing instead.

Stamina-limited movement continuation policy

stamina_fail: break
stamina_fail: continue

movement: approach defaults to break. If Stamina prevents the battler from reaching the authored approach destination, the affordable partial move finishes and the remaining sequence is skipped. Implicit animation, impact, and damage therefore do not occur.

Use stamina_fail: continue when partial movement is intentional. Other movement modes default to continue and may opt into break explicitly.

movement: approach — direct target vector

approach calculates direction as target - user, so left/right/up/down/diagonal travel always follows the target's actual relative position.

movement: approach
target: target
distance: 100
speed: 10

distance is the desired remaining spacing from the target. Stamina is applied afterward to the calculated travel distance, so stamina-limited movement still travels in the correct direction.

Command-local selector isolation

Implicit ASH steps execute only their authoritative parsed command. Local selector/argument keys cannot accidentally dispatch another registered command.

stamina_set: user, 10

The local user selector no longer executes the standalone target: command or changes the action's current target. Explicit standalone target: remains supported.

Uncapped current Stamina

Current Stamina can exceed maxStamina(). The max remains the normal battle-start/full-refill reference amount.

stamina_set: user, 10000

This now gives 10,000 current Stamina. staminaRate() may therefore exceed 1.0. Stamina still cannot go below zero.

Automatic attack pose after successful approach

A successful automatically-posed movement: approach now transitions from semantic walk to semantic attack before the implicit database animation and damage phase.

movement: approach
target: target
distance: 0
speed: 10

damage: true

Explicit pose authoring remains authoritative. Failed Stamina-gated approaches return to idle and break without entering the attack pose.

Home movement aliases

movement: home, return, and returnHome route to Current Home.

movement: originalHome, returnOriginal, returnOriginalHome, and original route to Original Home.

setHome/updateHome changes Current Home only.

Explicit-only movement Stamina

Movement does not consume Stamina unless stamina: true is authored on that movement instruction.

movement: approach
target: target
distance: 100
speed: 10
stamina: true

Ordinary movement never updates Current Home. Only explicit setHome/updateHome calls change it.

Parsed / Reserved — Not Currently Executed

Generic Core examples that are not feature contracts

<ASH Encounter: 5> and <ASH CanEscape: true> appear as generic Core parser examples, but no active gameplay consumer was found in the supplied stack.