View source for Didhitscript

<code>didhitscript</code> is a model event that runs on the entity conferring a successfully accepted hit. It provides the attacker, recipient, and raw attack properties to script after OpenBOR has determined the collision will count as a hit.

The event is hit confirmation rather than damage confirmation. It also runs when the recipient blocks, when an accepted hit produces no actual HP loss, when an item is collected, and when configured landing damage is applied. It does not run for misses, rejected collisions, counters, or attacks cancelled by <code>ondoattackscript</code>.

== Syntax ==

<syntaxhighlight lang="text">
didhitscript {path}

# Default
# No Didhit script
</syntaxhighlight>

* <code>{path}</code> - 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:

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

didhitscript data/scripts/example_didhit.c
</syntaxhighlight>

Event code may also be embedded directly in the model:

<syntaxhighlight lang="c">
didhitscript @script
void main()
{
    void self        = getlocalvar("self");
    void recipient   = getlocalvar("damagetaker");
    int blocked      = getlocalvar("blocked");
}
@end_script
</syntaxhighlight>

== Event Scope ==

OpenBOR invokes <code>didhitscript</code> for the following native events.

{| class="wikitable"
! Event
! <code>self</code>
! <code>damagetaker</code>
! Notes
|-
| Normal accepted hit
| Entity whose attack box supplied the hit
| Recipient
| Runs after the recipient's take-damage handling succeeds. <code>blocked</code> is <code>0</code>.
|-
| Successful block
| Attacking entity
| Blocking entity
| A block still counts as a successful hit. <code>blocked</code> is <code>1</code>.
|-
| Item collection
| Item entity
| Collecting entity
| OpenBOR supplies an otherwise empty attack object with type <code>ATK_ITEM</code>. Other numeric attack locals are normally <code>0</code>.
|-
| Damage on landing
| Living opponent credited for the fall, or the landing entity when no valid opponent exists
| Landing entity
| Runs after landing damage and death checks. <code>blocked</code> is <code>0</code>.
|}

<code>self</code> is always the entity directly conferring the event. Projectiles therefore receive their own Didhit events; OpenBOR does not automatically substitute the projectile's owner. Scripts may inspect the entity's owner when they need to credit or notify the top-level character.

One attack may run the event several times when it legitimately hits several recipients. Normal attack-ID, next-hit-time, faction, vulnerability, ground-hit, juggle, and other collision rules still decide whether each candidate is accepted.

<code>didhitscript</code> is not a universal health-change callback. Direct script changes to health and unrelated damage paths do not automatically invoke it.

== Execution Timing ==

=== Normal Hit ===

For an ordinary unblocked hit, OpenBOR performs the relevant operations in this order:

# Confirms collision, faction, timing, vulnerability, and other attack eligibility.
# Runs the recipient's <code>ondoattackscript</code>, followed by the attacker's <code>ondoattackscript</code>.
# Continues only when the shared last-hit confirmation remains enabled.
# Rejects blocking and counter actions.
# Runs the recipient's take-damage handling, including applicable offense, defense, HP, effect, pain, fall, and death processing.
# Runs the attacker's <code>didhitscript</code> with <code>blocked = 0</code>.
# Continues attacker-side hit counting, flash, pause, follow-up, combo, sound, and related processing.

The recipient's current state is therefore available when Didhit runs, including HP and the reaction selected by take-damage handling. The <code>damage</code> local still contains the attack's raw force rather than the final HP amount removed.

=== Blocked Hit ===

For a successful block, OpenBOR performs the following relevant sequence:

# Selects the native block reaction when applicable.
# Spawns the block flash.
# Runs the attacker's <code>didhitscript</code> with <code>blocked = 1</code>.
# Applies native blocking state, movement, and guard-cost handling when applicable.
# Counts the impact as a hit.
# Runs the defender's <code>didblockscript</code>.
# Applies configured chip damage and plays the block impact sound.

Consequently, <code>blocked = 1</code> means the recipient successfully blocked the impact. It does not mean the recipient is guaranteed to lose no HP, because chip damage may follow.

== Local Variables ==

{| class="wikitable"
! Local variable
! Type
! Value
|-
| <code>self</code>
| Entity pointer
| Entity conferring the hit. Usually the attacker, projectile, or collected item.
|-
| <code>damagetaker</code>
| Entity pointer
| Entity receiving the hit, blocking it, collecting the item, or taking landing damage.
|-
| <code>damage</code>
| Integer
| Raw <code>attack.damage.force</code> at the time of the event. This is not the final HP loss after offense, defense, blocking, or other adjustments.
|-
| <code>drop</code>
| Integer
| Raw <code>attack.reaction.fall.force</code> - the attack's knockdown force.
|-
| <code>attacktype</code>
| Integer
| Internal attack-type identifier. Compare it with named <code>ATK_*</code> constants from <code>openborconstant()</code>, not creator-facing model-text numbers.
|-
| <code>noblock</code>
| Integer
| Raw <code>attack.block.penetrate</code> value. The local retains its legacy name.
|-
| <code>guardcost</code>
| Integer
| Raw <code>attack.block.cost</code> value.
|-
| <code>jugglecost</code>
| Integer
| Attack's juggle-point cost.
|-
| <code>pauseadd</code>
| Integer
| Raw <code>attack.reaction.pause.time</code> in logical clock ticks.
|-
| <code>tag</code>
| Integer
| Creator-defined <code>attack.tag</code> metadata.
|-
| <code>blocked</code>
| Integer
| <code>1</code> when the recipient successfully blocked the attack; otherwise <code>0</code>.
|}

The numeric locals are event values copied from the current attack. Assigning new values to these local variables does not write them back to native attack data or undo completed hit handling.

Use <code>ondoattackscript</code> and the last-hit interface when a script must inspect, modify, or cancel a collision before native hit resolution. Use <code>didhitscript</code> for reactions that should occur only after OpenBOR accepts the hit.

== Global Model ==

Models loaded with the internal name <code>global_model</code> may provide a project-wide Didhit script.

<syntaxhighlight lang="text">
# data/models.txt
load global_model data/chars/global_model.txt
</syntaxhighlight>

<syntaxhighlight lang="text">
# data/chars/global_model.txt
name global_model
didhitscript data/scripts/global_didhit.c
</syntaxhighlight>

When an event occurs, OpenBOR executes scripts in this order:

# The loaded <code>global_model</code> Didhit script.
# The conferring entity's own Didhit script.

Both scripts receive the same event locals. Within the global script, <code>self</code> is the actual attacker, projectile, item, or landing-damage source - not a <code>global_model</code> entity. The global model must be loaded before its event script is available.

== Example ==

The following script distinguishes ordinary hits, blocked hits, and item collection. The log calls are intentionally simple and may be replaced with project-specific functions.

<syntaxhighlight lang="c">
void main()
{
    void self          = getlocalvar("self");
    void recipient     = getlocalvar("damagetaker");
    int attack_type    = getlocalvar("attacktype");
    int raw_force      = getlocalvar("damage");
    int was_blocked    = getlocalvar("blocked");

    if(attack_type == openborconstant("ATK_ITEM"))
    {
        log("Didhit: item collection");
        return;
    }

    if(was_blocked)
    {
        log("Didhit: blocked attack");
        return;
    }

    log("Didhit: accepted unblocked attack");
}
</syntaxhighlight>

Unused locals in the example are retained to show the ordinary event setup. Real scripts may pass <code>self</code>, <code>recipient</code>, <code>attack_type</code>, and <code>raw_force</code> into creator-defined hit-confirm, resource, statistics, effect, or achievement systems.

== Related Events ==

{| class="wikitable"
! Event
! Entity
! Relative purpose
|-
| [[Ondoattackscript]]
| Recipient first, then attacker
| Runs before block, counter, and take-damage resolution. May cancel native hit handling through the last-hit confirmation interface.
|-
| [[Takedamagescript]]
| Recipient
| Runs while native damage is being applied to the target.
|-
| [[Didhitscript]]
| Attacker or other conferring entity
| Runs after OpenBOR accepts a normal hit, block, item event, or landing-damage event.
|-
| [[Didblockscript]]
| Defender
| Runs after a successful block and after applicable native guard-cost deduction.
|}

== See Also ==

* [[Collision]]
* [[Attack Type]]
* [[Blocking]]
* [[Damage Control]]
* [[Model Registry]]
* [[Script Overview]]

[[Category:Openbor]]
[[Category:Model]]
[[Category:Script]]