Onfallscript

onfallscript is OpenBOR's fall-entry hook. It runs after the engine successfully selects a fall animation and establishes the entity's native falling state.

This placement gives creators direct control at the point where knockback becomes an active fall. Scripts can inspect the attacker and attack metadata, reshape launch velocity, route different knockdowns into custom states, enable air recovery, begin wall or ground bounce systems, add fall-specific effects, coordinate juggle rules, or select specialized defeat presentation.

Onfall is not a general airborne or per-frame callback. Jumping, changing vertical velocity, or directly playing a fall animation does not invoke it. The event belongs to OpenBOR's native fall selector and runs once each time that selector succeeds.

Syntax

onfallscript {path}

# Default
# No Onfall script

{path} - Path to an OpenBOR Script source file.
The command belongs in a model definition.
OpenBOR loads and compiles the script with the model.
The script's return value is ignored.

Example model definition:

name example_character
type enemy

onfallscript data/scripts/example_onfall.c

Event code may also be embedded directly in the model:

onfallscript @script
void main()
{
    void self        = getlocalvar("self");
    void attacker    = getlocalvar("attacker");
    int damage       = getlocalvar("damage");
    int drop         = getlocalvar("drop");
    int attack_type  = getlocalvar("attacktype");
    int tag          = getlocalvar("tag");
}
@end_script

Event Timing

For an ordinary accepted hit that causes a fall, OpenBOR performs the relevant operations in this order:

Resolves Ondoattack, blocking, counters, weapon loss, damage effects, direction, and knockdown eligibility.
Calculates and applies HP damage.
Runs Takedamagescript.
Runs Ondeathscript when the damage path enters its lethal branch.
Commits native death state when HP remains at or below 0.
Chooses fall handling when the recipient is knocked down or remains at or below 0.
Allows an applicable native death sequence to replace the ordinary fall path.
Applies the attack's X, Y, and Z launch velocity, landing-damage data, knockdown counters, and fall action.
Selects and starts a valid front-fall or back-fall animation.
Establishes native fall flags, clears conflicting action states, prevents grabbing, and removes frozen state.
Runs onfallscript.
Returns to recipient damage handling, followed by the conferrer's Didhitscript.

Current fall animation and launch velocity are already active when Onfall begins. The callback may inspect or replace either one. Normal damage performs no later fall selection after the callback returns.

Lethal hits have already passed Takedamage, Ondeath, and checkdeath() before Onfall. Restoring HP during Onfall does not automatically clear committed death state or reverse score, boss, drop-item, and death-sound processing. Use Takedamage or Ondeath when death must be prevented.

Native Fall Selection

OpenBOR uses the following general selection order before invoking Onfall:

Select the attack-type back-fall animation when the entity entered the hit from back pain.
Otherwise select the attack-type front-fall animation.
Fall back to generic back fall when available.
Fall back to the attack-type front fall and clear back-pain orientation when needed.
Fall back to generic front fall.
Abort without invoking Onfall when no valid fall animation exists.

The attacktype local contains the requested attack type, not the final animation identifier. Missing type-specific animation data may therefore produce a generic fall while the original type remains available to script.

Unlike the pain selector, the fall selector does not replace missing fall data with idle. Ordinary damage may remove an entity when no usable fall animation exists.

Practical Uses

Pattern	Use of `onfallscript`
Air recovery or ukemi	Check current input, resources, attack type, and project rules as the fall begins, then replace eligible knockdown with an air-tech or controlled recovery.
Wall or ground bounce routing	Use `tag`, `attacktype`, position, and current velocity to arm wall splats, rebounds, floor bounces, sliding knockdowns, or ricochet states.
Launch and knockback shaping	Scale, clamp, redirect, or replace X, Y, and Z velocity for weight classes, armor states, attack categories, cinematic hits, or arena-specific behavior.
Juggle and combo control	Record the fall source, spend or restore juggle resources, open combo routes, activate escape rules, or notify a combo controller that true knockdown began.
Throw-specific behavior	Detect the credited thrower and route held targets into project-specific slam, launch, rebound, team-combo, or synchronized fall systems.
Defeat presentation	Choose burning, freezing, shattering, disintegration, slow-motion, camera, sound, dialogue, or other fall presentation from attack type, tag, attacker, and committed death state.
Environmental interaction	Redirect falls near ledges, hazards, platforms, walls, breakable scenery, pits, or scripted arena boundaries.
Combat feedback and telemetry	Add readable launch flashes, indicators, voices, accessibility feedback, statistics, or debugging data only when native fall entry actually occurs.

Air Recovery

The following compact example hands eligible nonlethal falls to a project helper. Helper try_air_recovery() may check current input and meter, reject forbidden attack types or tags, then establish the complete recovery animation, action state, velocity, and invincibility rules.

void main()
{
    void self = getlocalvar("self");
    void attacker = getlocalvar("attacker");
    int attack_type = getlocalvar("attacktype");
    int tag = getlocalvar("tag");
    int health = getentityproperty(self, "health");

    if(health > 0)
    {
        try_air_recovery(self, attacker, attack_type, tag);
    }
}

The helper runs exactly when native fall begins rather than polling every update. Project rules remain free to make recovery automatic, input-timed, resource-gated, attacker-dependent, or unavailable for selected attacks.

Local Variables

Local variable	Type	Value
`self`	Entity pointer	Entity whose fall selector succeeded and whose Onfall script is running.
`attacker`	Entity pointer	Entity supplied as the fall source. Projectiles remain the source entity; OpenBOR does not automatically substitute their owner. Synthetic paths may supply `self`.
`damage`	Integer	Attack's `attack.damage.force` value supplied to fall handling. For ordinary hits this is normally raw force, not final HP loss after offense and defense.
`drop`	Integer	Raw `attack.reaction.fall.force` - the attack's knockdown force. This is attack metadata, not the entity's current fall-state flag.
`attacktype`	Integer	Requested attack-type identifier used for fall-animation selection. Compare it with named `ATK_*` constants from `openborconstant()`.
`noblock`	Integer	Raw `attack.block.penetrate` value. The local retains its legacy name.
`guardcost`	Integer	Raw `attack.block.cost` value.
`jugglecost`	Integer	Attack's juggle-point cost.
`pauseadd`	Integer	Raw `attack.reaction.pause.time` in logical clock ticks.
`tag`	Integer	Creator-defined `attack.tag` metadata.

Numeric locals are copied from the attack object used to enter fall. Assigning new values to these locals does not change the attack, animation, velocity, or entity state.

The event does not provide reset, blocked, which, attack_id, final HP loss, or landing-damage values. Use entity and attack property interfaces when native objects must be inspected or changed.

Attack Context and Fall Outcome

The local variables describe the attack object supplied to the fall selector. They do not guarantee that the fall came from ordinary HP damage.

Native throws illustrate the distinction. Throw handling supplies the thrower as attacker, but enters the fall selector with a default attack object. Values such as damage, drop, and tag are therefore normally 0, while throw damage is stored separately for the later landing event.

Stage-wide knockdowns, projectile floor death, and projectile ricochet also use default or synthetic attack data. These paths commonly report self as attacker. Creators should combine event locals with entity type, owner, current state, health, position, and project variables when the exact source matters.

Event Scope

Path	Onfall event	Notes
Accepted nonlethal knockdown	Yes	Runs after native launch motion, fall animation, and fall state are established.
Lethal accepted hit	Usually	Runs when native death handling continues through ordinary fall selection. Death sequences may substitute another path.
Hit that produces standing pain	No	Uses Onpainscript after standing pain selection.
Successful native block or counter	No	Native hit processing does not enter the fall selector.
Native throw	Yes	Supplies the thrower as `attacker`, with default attack metadata and separately scheduled landing damage.
Stage-wide enemy knockdown	Yes	Used when a player re-enters play and eligible enemies are dropped. Each affected enemy receives its own callback.
Projectile floor death or wall ricochet	Yes	These specialized paths explicitly enter fall selection with synthetic attack context.
Damage on landing	Not for the same completed fall	Landing damage suppresses immediate fall re-entry, preventing the same landing from starting another fall callback.
Later hit against a falling entity	Possible again	Another accepted hit may reselect fall and invoke Onfall for the new event.
Jump, toss, gravity, or scripted velocity alone	No	Airborne motion does not itself invoke the fall selector.
Direct animation change to a fall animation	No	Onfall belongs to native fall selection, not to the animation identifier.
Fall request without a valid fall animation	No	The selector returns without running the script.

Onfall therefore means successful native fall entry, not simply airborne state, HP loss, knockdown force, or eventual contact with the ground.

Changing the Fall

The native animation, velocity, fall flags, no-grab state, and surrounding fall action are already active when the callback begins. Scripts may redirect motion, replace the animation, begin an attack or recovery, transfer control to a custom state machine, or record context for landing behavior.

Replacing only the animation may leave native fall action logic active. Project helpers should establish every action, movement, vulnerability, landing, and recovery state required by the replacement.

The script return value is ignored. Returning 0 does not cancel the fall, and returning 1 does not confirm it.

Changing lasthitc during Onfall is too late to cancel the hit. Use Ondoattackscript when collision, damage, launch, and all other native consequences should be rejected.

Attacker Identity

For an ordinary hit, attacker is the entity whose attack entered recipient damage handling. Projectiles therefore appear as themselves rather than their owner. Scripts needing credit for the controlling character may follow owner or parent relationships.

Synthetic fall paths may supply self because no separate combat source exists. Attack type and tag are useful discriminators for ordinary attacks, while entity state and project variables are more reliable for default synthetic contexts.

Global Model

onfallscript is not automatically forwarded through a model named global_model. Only the script belonging to the entity entering fall runs. Shared project-wide behavior should be placed in a common script included by participating models or called from their individual Onfall scripts.

Related Events

Event	Entity	Relative purpose
Ondoattackscript	Recipient first, then conferrer	Runs before native hit resolution and may cancel all native consequences through `lasthitc`.
Takedamagescript	Damage recipient	Runs after HP processing, before death commitment and fall selection.
Ondeathscript	Damage recipient	Runs during lethal damage before native death commitment and any following fall selection.
Onpainscript	Entity entering standing pain or grabbed selection	Runs when reaction handling chooses pain instead of fall.
Onfallscript	Entity entering fall	Runs after a valid fall animation, launch motion, and native fall state are established.
Didhitscript	Conferrer	Runs after accepted recipient take-damage handling, including Onfall when applicable.
Onkillscript	Entity being removed	Runs later when OpenBOR removes the entity from active play.