Dcurrent at 00:52, 19 August 2026

2026-08-19T00:52:14Z

← Older revision		Revision as of 20:52, 18 August 2026
Line 274:		Line 274:
	* [[Binding]]		* [[Binding]]
	* [[Movement configuration]]		* [[Movement configuration]]
			[[Category:Model]]
			[[Category:Openbor]]
			[[Category:Script]]

Dcurrent: Created page with "`onmovexscript`, `onmoveyscript`, and `onmovezscript` define model-level hooks for responding to entity movement along OpenBOR's three world axes. Each hook executes after a qualifying movement stage for its axis and receives the moving entity as `self`. These hooks are useful for movement effects, environmental interaction, trails, custom physics, camera logic, state tracking, sound control, movement-dependent attacks, and ot..."

2026-08-19T00:49:56Z

Created page with "<code>onmovexscript</code>, <code>onmoveyscript</code>, and <code>onmovezscript</code> define model-level hooks for responding to entity movement along OpenBOR's three world axes. Each hook executes after a qualifying movement stage for its axis and receives the moving entity as <code>self</code>. These hooks are useful for movement effects, environmental interaction, trails, custom physics, camera logic, state tracking, sound control, movement-dependent attacks, and ot..."

New page

<code>onmovexscript</code>, <code>onmoveyscript</code>, and <code>onmovezscript</code> define model-level hooks for responding to entity movement along OpenBOR's three world axes. Each hook executes after a qualifying movement stage for its axis and receives the moving entity as <code>self</code>.

These hooks are useful for movement effects, environmental interaction, trails, custom physics, camera logic, state tracking, sound control, movement-dependent attacks, and other systems that should react to motion rather than run continuously.

The hooks are related by purpose, though their native triggers are not identical. X and Z report successful collision-aware lateral movement. Y reports active vertical velocity during gravity processing.

== Hook Summary ==

{| class="wikitable"
! Model command
! Axis
! Native trigger
|-
| <code>onmovexscript</code>
| X - Horizontal level position
| Collision-aware lateral movement accepts a nonzero X displacement.
|-
| <code>onmoveyscript</code>
| Y - Vertical altitude
| Gravity processing leaves the entity with nonzero Y velocity.
|-
| <code>onmovezscript</code>
| Z - Lateral level depth
| Collision-aware lateral movement accepts a nonzero Z displacement.
|}

The commands do not form a universal observer for every position change. Direct property assignment, binding, and several specialized placement systems can move an entity without invoking them.

== Syntax ==

<syntaxhighlight lang="text">
onmovexscript {path}
onmoveyscript {path}
onmovezscript {path}

# Default
# No corresponding Onmove script
</syntaxhighlight>

* <code>{path}</code> - Path to an OpenBOR Script source file.
* Each command belongs in a model definition.
* OpenBOR loads and compiles each supplied source with the model.
* Each source defines a normal <code>main()</code> entry point.
* Script return values are ignored.

Example model header:

<syntaxhighlight lang="text">
name example_entity
type enemy

onmovexscript data/scripts/example_move_x.c
onmoveyscript data/scripts/example_move_y.c
onmovezscript data/scripts/example_move_z.c
</syntaxhighlight>

Event code may also be embedded directly in the model:

<syntaxhighlight lang="c" line>
onmoveyscript @script
void main()
{
void self = getlocalvar("self");
float velocity_y = get_entity_property(
self,
ENTITY_PROPERTY_VELOCITY_Y
);

update_vertical_effect(self, velocity_y);
}
@end_script
</syntaxhighlight>

<code>update_vertical_effect()</code> in this example represents a project-defined function.

== Local Variables ==

All three hooks receive the same local:

{| class="wikitable"
! Local
! Type
! Value
|-
| <code>self</code>
| Entity pointer
| Entity whose movement triggered the script.
|}

No displacement, velocity, direction, movement source, collision result, platform, or logical time is supplied automatically. Retrieve current values from <code>self</code> or project-managed state when needed.

Useful entity properties include:

* <code>ENTITY_PROPERTY_POSITION_X</code>
* <code>ENTITY_PROPERTY_POSITION_Y</code>
* <code>ENTITY_PROPERTY_POSITION_Z</code>
* <code>ENTITY_PROPERTY_VELOCITY_X</code>
* <code>ENTITY_PROPERTY_VELOCITY_Y</code>
* <code>ENTITY_PROPERTY_VELOCITY_Z</code>
* <code>ENTITY_PROPERTY_MOVE_X</code>
* <code>ENTITY_PROPERTY_MOVE_Z</code>

The X and Z move properties are working movement accumulators during lateral processing. They should not be assumed to contain a finalized accepted displacement while an Onmove callback is still executing.

== X and Z Movement ==

<code>onmovexscript</code> and <code>onmovezscript</code> execute from OpenBOR's collision-aware lateral movement handler. The handler first tests screen limits, holes, obstacles, platforms, walls, and the final destination. Accepted movement is then applied to both lateral coordinates before either callback executes.

After placement:

# <code>onmovexscript</code> executes when the accepted X displacement is nonzero.
# <code>onmovezscript</code> executes when the accepted Z displacement is nonzero.

Diagonal movement can therefore execute both hooks. X executes first, followed by Z. Both callbacks observe the already-updated X and Z position.

When one axis is blocked and the other remains valid, only the successful axis hook executes. Fully rejected movement executes neither hook. Related [[Onblock scripts]] may execute earlier during the collision tests.

=== Movement Sources ===

Lateral movement can reach these hooks from several native sources:

* Walking, running, and native artificial intelligence movement.
* X or Z velocity accumulated during the entity update.
* Animation-configured lateral movement.
* Moving-platform carry when the rider uses collision-aware movement.
* Native grab-walking and linked movement that routes through the same handler.

More than one collision-aware movement operation can occur during a single logical cycle. Platform carry may occur before the entity applies its own movement, for example. X and Z callbacks are therefore event-driven and are not limited to one execution per logical cycle.

Some entity types intentionally use direct lateral placement instead of the collision-aware movement handler. Their X and Z position can change without executing these hooks.

== Y Movement ==

<code>onmoveyscript</code> belongs to gravity processing rather than the lateral collision handler. OpenBOR first applies the entity's existing Y velocity to its position, calculates gravity, updates and limits Y velocity, and evaluates the configured drop-position transition. Onmoveyscript then executes when the resulting Y velocity is nonzero.

Positive Y velocity moves upward. Negative Y velocity moves downward.

The trigger is based on velocity after gravity and speed limiting, not a direct comparison between old and new Y positions. Consequences include:

* The hook may execute when gravity has just created nonzero velocity even if Y position did not change earlier in that same gravity pass.
* The hook does not execute when velocity becomes exactly zero, even if the previous velocity already changed Y position during that pass.
* Landing resolution occurs after the callback, so the entity may be at or below its base while Onmoveyscript still reports the final active downward velocity.

Changes made by Onmoveyscript occur before native landing resolution. Script may inspect or modify position, velocity, animation, damage, or other state used by the remaining landing logic. Its return value does not cancel the native process.

Direct Y placement, moving-platform base correction, and binding do not invoke Onmoveyscript merely because they changed altitude. The hook specifically belongs to active gravity processing with nonzero resulting Y velocity.

== Runtime Order ==

The usual logical-cycle order is:

# [[Updateentityscript]] executes during the entity's main update when eligible.
# Native action, thinking, and animation processing continue.
# Attack collision and health-display processing occur.
# X and Z velocity are added to pending lateral movement.
# Post-update processing begins with base adjustment and gravity.
# Y position and velocity are processed.
# <code>onmoveyscript</code> executes when resulting Y velocity is nonzero.
# Native landing processing continues.
# Pending X and Z movement is tested and applied.
# <code>onmovexscript</code> executes for accepted X movement.
# <code>onmovezscript</code> executes for accepted Z movement.
# Binding resolves after movement is complete.

Onmoveyscript normally precedes the lateral hooks during the post-update pass. Binding occurs later and does not retroactively execute an Onmove script for position changes it applies.

== Changes That Do Not Trigger the Hooks ==

The following operations do not inherently execute an Onmove hook:

* Assigning <code>ENTITY_PROPERTY_POSITION_X</code>, <code>ENTITY_PROPERTY_POSITION_Y</code>, or <code>ENTITY_PROPERTY_POSITION_Z</code> directly.
* Repositioning an entity through binding.
* Native base correction placing an entity onto vertically moving terrain.
* Lateral movement performed by an entity type without a collision-aware movement handler.
* Rejected movement that leaves the applicable lateral displacement at zero.
* Vertical processing whose resulting Y velocity is zero.

Scripts needing to observe every possible coordinate change should compare stored and current positions from a general update hook. Onmove scripts are targeted callbacks for specific native movement paths, not global property-change events.

== Frozen and Fresh Entities ==

Frozen entities do not apply their own ordinary lateral or vertical movement, so their Onmove hooks normally remain inactive. Moving-platform carry is processed before the rider's lateral freeze check, allowing X or Z callbacks when a frozen rider is carried through collision-aware movement.

Onmoveyscript remains suppressed while the entity is frozen because active gravity movement is skipped.

Freshly spawned entities skip the main entity update during their spawn cycle, though they still participate in post-update processing. Existing pending movement, platform carry, or vertical state can consequently produce an Onmove callback during that cycle. Pausing the logical engine prevents the normal update pass from advancing.

== Return Values and Script Changes ==

Return values are ignored for all three hooks.

X and Z collision decisions are complete before their callbacks execute. Returning a value cannot restore a blocked movement axis. Direct position changes made by script remain possible, though those changes bypass the collision checks that preceded the callback.

Y executes before native landing resolution. Returning a value still has no control effect, though property changes may influence the logic that follows because the engine reads the modified entity state afterward.

== Quick Examples ==

=== Lateral Movement Effect ===

The same project function can be called from separate X and Z scripts. Systems that should run only once for diagonal movement must guard against both hooks executing during the same operation.

<syntaxhighlight lang="c" line>
void main()
{
void self = getlocalvar("self");
float x = get_entity_property(
self,
ENTITY_PROPERTY_POSITION_X
);
float z = get_entity_property(
self,
ENTITY_PROPERTY_POSITION_Z
);

update_lateral_trail(self, x, z);
}
</syntaxhighlight>

=== Rising and Falling Effects ===

Onmoveyscript can select behavior from the post-gravity velocity sign:

<syntaxhighlight lang="c" line>
void main()
{
void self = getlocalvar("self");
float velocity_y = get_entity_property(
self,
ENTITY_PROPERTY_VELOCITY_Y
);

if(velocity_y > 0)
{
update_rising_effect(self, velocity_y);
}
else if(velocity_y < 0)
{
update_falling_effect(self, velocity_y);
}
}
</syntaxhighlight>

The called functions in these examples are project-defined and illustrate routing rather than a complete effect system.

== Common Uses ==

* Producing footsteps, dust, wakes, skid effects, or movement trails.
* Updating terrain interaction while an entity moves laterally.
* Applying ascent, fall, or wind effects according to Y velocity.
* Coordinating movement-dependent audio.
* Recording accepted lateral movement for custom state systems.
* Adjusting camera or interface behavior according to entity motion.
* Extending native movement without running equivalent work during stationary cycles.

== Common Mistakes ==

* Treating the hooks as universal observers for all coordinate changes.
* Expecting blocked X or Z movement to execute the corresponding Onmove script.
* Expecting direct position assignment or binding to invoke a hook.
* Assuming X and Z callbacks execute no more than once per logical cycle.
* Forgetting that diagonal movement executes X first and then Z.
* Reading <code>ENTITY_PROPERTY_MOVE_X</code> or <code>ENTITY_PROPERTY_MOVE_Z</code> as a finalized displacement during the callback.
* Assuming Onmoveyscript proves that Y position changed during the same gravity pass.
* Expecting Onmoveyscript when direct placement changes altitude with zero Y velocity.
* Returning a value and expecting movement or landing logic to be cancelled.
* Producing the same lateral effect twice when both X and Z callbacks handle one diagonal movement.

== See Also ==

* [[Geometry Overview]]
* [[Entity properties]]
* [[Updateentityscript]]
* [[Animationscript]]
* [[Binding]]
* [[Movement configuration]]

Move Position Events - Revision history

Dcurrent at 00:52, 19 August 2026