Msw Combat System

msw-combat-system

The full MSW combat pipeline. Covers only items in the common 2D combat layer that have MSW native API support, regardless of genre. Excludes formulas/theory. API signatures are based on Environment/NativeScripts/**/*.d.mlua.

---

0. Coverage matrix

---

0.5 References — where to go

This SKILL.md covers only the system flow and native API surface. Actual model JSON, full script code, and variation patterns are in the references/* files below — Read them directly.

Priority: *this SKILL.md (concepts + API tables) → the relevant references/ (full implementation)**.

---

1. Attack Resolution

1-1. Shape & Attack trigger

HitComponent.ColliderType supports only Box / Circle / Polygon. Other shapes must be approximated by composition.

AttackComponent:
  Attack(Vector2 size, Vector2 offset, string attackInfo, CollisionGroup? cg)    → table<Component>
  Attack(Shape shape, string attackInfo, CollisionGroup? cg)                     → table<Component>
  AttackFast(Shape shape, string attackInfo, CollisionGroup? cg)                 → void   (for mass resolution, bullet hell)
  AttackFrom(Vector2 size, Vector2 position, string attackInfo, CollisionGroup? cg) → table<Component>
  emitter EmitAttackEvent(AttackEvent)

• Shapes: CircleShape(position, radius) / BoxShape(position, size, angle) / PolygonShape(position, points, angle). For an axis-aligned rectangle, use BoxShape(center, size, 0) — there is no RectangleShape type. Pass angle = 0 to BoxShape / PolygonShape when no rotation is needed.
• Polygon hit surface: HitComponent.PolygonPoints: SyncList<Vector2>
• AttackFast does not build a hit table → better performance for bullet hell / mass resolution

1-2. Target filter

If either returns false → the hit is excluded. The super call is `__base:IsAttackTarget(...)` (mlua-specific).

⚠ Do not add `@ExecSpace` when overriding — both IsAttackTarget and IsHitTarget have an unspecified ExecSpace (=All) on the parent. Adding an annotation like @ExecSpace("ServerOnly") in the child triggers LEA-3014 `SignatureMismatch` at runtime. Even without the annotation, the call path runs through the server-side hit pipeline, so actual execution happens on the server. Details: `msw-scripting/SKILL.md` §9 "Method override".

• HitComponent.CollisionGroup defaults to CollisionGroups.HitBox. The last argument of Attack(..., cg) specifies the target group.
• Duplicate-hit prevention / pierce / max hits: not native. Manage in script via the table returned by Attack + a table<Entity, boolean> cache.

1-3. attackInfo tagging

A string extension point that propagates into CalcDamage/IsHitTarget/GetDisplayHitCount. Value conventions are up to the project. A namespace style such as "melee.light", "dot.poison" is recommended.

1-4. ⚠️ IsLegacy

ColliderType/ColliderOffset/PolygonPoints are only valid when HitComponent.IsLegacy = false. BoxOffset/ColliderName are deprecated.

1-5. Shape mapping per attack form

There is no MSW-specific projectile system — implemented as an entity + AttackComponent combo.

1-6. Continuous movement — common rules for projectiles, monsters, and AI

Continuous movement (chase, flight, auto-move) is per-frame `OnUpdate(delta)`-based. Moving via a timer (SetTimerRepeat(0.1~0.15s)) produces 6~10Hz teleportation that looks choppy.

Recommended API per target

For the actual velocity conversion of MovementComponent.InputSpeed per map type, see `msw-general/references/platform.md` §10 (MapleTile=×1, RectTile=÷1.2, SideView=×1.5).

Forbidden patterns

⚠ Be cautious with the official msw-search antipattern

mlua_Document_Retriever returns a high-scoring "Entity Movement Control Using MovementComponent" document, but the body is an antipattern that moves every frame inside OnUpdate with MovementComponent:SetPosition(...) — ignore that document and use MoveToDirection / Translate from the table above. FlappyFish Remake, Stopping the Taxi, and Making a Moving Foothold also show missing-delta or direct-Position assignment, so be careful when referring to them.

MovementComponent attachment — monsters / NPCs

Not included in the monster model by default. The .model must contain all of the following components.

Cross references

• Knockback (1-shot impulse) is not continuous movement, so use §3-1 directly.
• Body selection per map type / InputSpeed conversion: `msw-general/references/platform.md` §4·§10

---

2. Damage Model

AttackComponent:
  method integer CalcDamage(attacker, defender, attackInfo)        -- default 1     (ExecSpace=All)
  method boolean CalcCritical(attacker, defender, attackInfo)      -- default false (ExecSpace=All)
  method float   GetCriticalDamageRate()                           -- default 2.0   (ExecSpace=All)
  method int32   GetDisplayHitCount(attackInfo)                    -- default 1     (ExecSpace=All)
  method void    OnAttack(defender)                                                 -- (ExecSpace=All)

HitComponent:
  method void OnHit(Entity attacker, integer damage, boolean isCritical, string attackInfo, int32 hitCount)
  emitter EmitHitEvent(HitEvent)

⚠ All hooks above have an unspecified ExecSpace (=All) on the parent. Adding @ExecSpace("ServerOnly") etc. when overriding triggers LEA-3014 `SignatureMismatch`. Drop the annotation and declare just method .... Details: `msw-scripting/SKILL.md` §9 "Method override".

2-1. HitEvent payload

AttackCenter:   Vector2
AttackerEntity: Entity (nilable)
Damages:        List<integer>    -- multi-hit split
Extra:          any              -- ★ extension slot (knockback/stun/element/tags)
IsCritical:     boolean
TotalDamage:    integer
FeedbackAction: HitFeedbackAction  -- ⚠ entire enum deprecated

Carry auxiliary info (knockback vector, stagger time, element) on the Extra table.

2-2. AttackEvent payload

A single field, DefenderEntity: Entity. The attacker is the handler's self.

2-3. ⚠️ Antipattern: direct HP subtraction — do not bypass HitEvent

Subtracting the defender's HP directly, such as monster.Hp -= damage / target.MonsterAI.HP -= damage, does not emit `HitEvent` — damage skin, hit effect, IsHitTarget immunity, and OnHit overrides all silently skip.

For player-side custom damage (channel / aura / DoT), the bypass also breaks avatar animation: AvatarStateAnimationComponent only reacts to StateChangeEvent, so the player avatar stays in idle even though the HP bar drops. If you must apply damage without HitEvent, also manually call StateComponent:ChangeState("HIT") (UPPERCASE key — see §10) and, for death/revive, PlayerComponent:ProcessDead() / ProcessRevive(). Otherwise hit/dead motions silently miss with no error.

---

3. Hit Reaction

3-1. Knockback — API per Body

• Rigidbody is auto-damped by the engine. Kinematic/Sideview must be damped manually inside OnUpdate (MoveVelocity *= 0.9).
• Wall bounce: subscribe to FootholdCollisionEvent and flip the velocity.
• Knockback is a 1-shot impulse — do not confuse it with continuous movement (chase, flight). For continuous movement see §1-6.
• ⚠ Forbidden: assigning TransformComponent.Position directly on an entity with an active Body → network sync is blocked. body:SetPosition(...) is a teleport method, so do not call it inside an OnUpdate loop (§1-6).

3-2. i-frame

Standard pattern: deadline check based on _UtilLogic.ElapsedSeconds + returning false from HitComponent:IsHitTarget. The DefaultPlayer default PlayerHit.mlua provides this pattern as-is (§9-4).

Alternative: while invincible, swap HitComponent.CollisionGroup to a separate group → the resolution itself is excluded. This is better for frame-accurate precision.

3-3. Status effects (Buff/Debuff)

No native support. Implement a @Component BuffComponent directly + tick with _TimerService:SetTimerRepeat + broadcast custom StatusAppliedEvent/StatusExpiredEvent.

For a single simple stun, StateComponent:ChangeState("STUN") + input/AI block flags is enough.

---

4. Game Feel — all native

PlayEffect options keys: FlipX, FlipY, SortingLayer, OrderInLayer, Alpha, StartFrameIndex, EndFrameIndex, PlayRate, SyncFlip, Color, MaterialID, IgnoreMapLayerCheck, LitMode

Get the current camera: _CameraService:GetCurrentCameraComponent().

ParticleService — built-in particles

General-purpose particle effects driven by enum values only, no RUID. 3 categories:

-- BasicParticle: general-purpose presets (no RUID needed)
integer _ParticleService:PlayBasicParticle(BasicParticleType, Entity instigator, Vector3 pos, number zRot, Vector3 scale, boolean isLoop, Dictionary options)
integer _ParticleService:PlayBasicParticleAttached(BasicParticleType, Entity parent, Vector3 localPos, number localZRot, Vector3 localScale, boolean isLoop, Dictionary options)

-- SpriteParticle: custom sprite as a particle (spriteRUID required)
integer _ParticleService:PlaySpriteParticle(SpriteParticleType, string spriteRUID, Entity instigator, Vector3 pos, number zRot, Vector3 scale, boolean isLoop, Dictionary options)
integer _ParticleService:PlaySpriteParticleAttached(SpriteParticleType, string spriteRUID, Entity parent, Vector3 localPos, number localZRot, Vector3 localScale, boolean isLoop, Dictionary options)

-- AreaParticle: environmental particles over a wide area (areaSize added)
integer _ParticleService:PlayAreaParticle(AreaParticleType, Vector2 areaSize, Entity instigator, Vector3 pos, number zRot, Vector3 scale, boolean isLoop, Dictionary options)

void _ParticleService:RemoveParticle(integer serial)

options keys: Color, SortingLayer, OrderInLayer, ParticleSize, ParticleCount

Looping particles (isLoop=true) must be cleaned up via RemoveParticle(serial). Store the serial in self._T so it can be removed later.

Full BasicParticleType list

Full SpriteParticleType list (8)

Full AreaParticleType list (12)

Choosing between EffectService and ParticleService

Standard pattern for server event → client effect: @Sync property change → detected in OnSyncProperty(ClientOnly) → call EffectService/ParticleService.

---

5. Death / Revive

Tracking the killer: DeadEvent has no payload → cache self.LastAttacker = event.AttackerEntity in HandleHitEvent and use it in HandleDeadEvent.

For player-specific death/revive, prefer §9-1 PlayerComponent.Respawn/ProcessDead/ProcessRevive.

---

6. Event Bus

6-1. Custom event rules

• Definition: @Event script XxxEvent extends EventType + property declarations
• Receiving: the handler keyword (not method), @EventSender("Self" | "Service","XxxService" | "Logic","XxxLogic")
• Connect/disconnect: entity:ConnectEvent(XxxEvent, self.Handler) / call `DisconnectEvent` in `OnEndPlay` (the engine does not auto-disconnect)
• Global: @Logic CombatEventBusLogic singleton + @EventSender("Logic","CombatEventBusLogic")

---

7. AI — FSM(StateComponent) + BT(AIComponent) + custom-script (Pattern A), all native-compatible

7-1. FSM — StateComponent (summary)

StateComponent + @State script XxxStateType extends StateType (lifecycle OnEnter/OnUpdate/OnExit/OnConditionCheck). The only auto-registered states are IDLE/DEAD (+ HIT if a HitComponent exists, MOVE if an AIChase/AIWander exists) — ATTACK/PATROL/STUN/PHASE2 etc. must all be pre-registered via AddState("name", XxxStateType) in OnBeginPlay. Auto transitions use AddCondition(from, to) + per-frame OnConditionCheck().

⚠ State names must be UPPERCASE; unregistered names immediately produce [LEA-3005] InvalidArgument : 'stateName'. Registering a key in AvatarStateAnimationComponent.StateToAvatarBodyActionSheet does not auto-register it in StateComponent — the two are separate.

Full implementation → [`../msw-general/references/animation-state.md`](../msw-general/references/animation-state.md) (FSM authoring, ChangeState failure matrix, standard PATROL/CHASE/ATTACK/HIT/DEAD monster pattern, and the state→animation pipeline live together — the two are the same underlying system viewed from two angles)

7-2. BT — AIComponent (summary)

AIComponent + SequenceNode/SelectorNode/RandomSelectorNode/ParallelNode + @BTNode Action Nodes + native AIChaseComponent/AIWanderComponent. All 4 Composite types are native; Decorator/Memory(Blackboard)/Threat Table must be implemented by hand.

⚠ When using custom BT, remove AIChaseComponent/AIWanderComponent from the .model.

Full implementation → [`references/ai-bt.md`](references/ai-bt.md)

Full monster entity composition → `../msw-general/references/monster.md`

>

This SKILL.md only covers combat-specific aspects (ATTACK/HIT/DEAD + DeadEvent/ReviveEvent + BT entry point). For general mlua state machine / scripting patterns see `msw-scripting`.

---

8. UI natives

Worldspace HP bar (overhead): no native support. Two implementation options:

---

9. DefaultPlayer combat natives

The player entity has HP, revive, and input natively. Do not create custom `Hp`/`MaxHp` properties — use PlayerComponent.

The full property/method tables for PlayerComponent / PlayerControllerComponent are in `msw-defaultplayer/SKILL.md`. Only combat essentials here.

9-1. Core combat APIs

9-3. PlayerActionEvent

property string ActionName       -- "Attack" / "Jump" / "Crouch" / ...
property Entity PlayerEntity

The default pattern is PlayerAttack extends AttackComponent that receives @EventSender("Self") handler HandlePlayerActionEvent(...) and branches on event.ActionName == "Attack".

9-4. Default templates (RootDesk/MyDesk/)

Copy-paste without modification. Override as needed:

9-5. Time reference

`_UtilLogic.ElapsedSeconds` is recommended (world clock, consistent across pause/restore). Do not use os.clock().

9-6. Standard CollisionGroups

---

10. Avatar motion — AvatarStateAnimationComponent

Auto-links StateComponent transitions to avatar animations.

@Sync property SyncDictionary<string, AvatarBodyActionElement> StateToAvatarBodyActionSheet  -- IsLegacy=false
@Sync property SyncDictionary<string, string>                  ActionSheet                    -- IsLegacy=true (deprecated)

method void   SetActionSheet(string key, string animationClipRuid)
method void   RemoveActionSheet(string key)
method string StateStringToAnimationKey(string stateName)
emitter EmitBodyActionStateChangeEvent(BodyActionStateChangeEvent)

• ChangeState("HIT") → the mapped MapleAvatarBodyActionState.Hit plays automatically
• Combat-relevant state values: Attack=3, Hit=14, Dead=10, Alert=4, Heal=13
• IsLegacy=false fixed; use only StateToAvatarBodyActionSheet

The full avatar component coverage (AvatarRendererComponent etc.) is in `msw-defaultplayer`. This section covers only combat motion mapping.

---

11. Damage skin (number display)

Default RUIDs

11-1. Auto mode (component-based)

On Attack/AttackFast, if all 3 components below are present, damage numbers are displayed automatically:

Include all 3 in the .model and damage numbers appear with zero script code.

DamageSkinSettingComponent (attacker)

DamageSkinTweenType: Default (popup) / Volcano (fan) / Blade (overlap) / each *Mini (75% scale)

DamageSkinSpawnerComponent (defender)

11-2. Manual mode — DamageSkinService

Cases not caught by auto mode (heal, Miss/Guard, non-standard damage sources) call _DamageSkinService directly.

_DamageSkinService:Play(targetEntity, skinRuid, delay, damages:List<int>, tweenType, isCritical, offset, scale, playRate, alpha, litMode)
_DamageSkinService:PlayTextDamage(targetEntity, skinRuid, textType, tweenType)
_DamageSkinService:PreloadAsync(skinRuid, callback(success))    -- ClientOnly

DamageSkinTextType: Miss / Guard / Resist / Shot / Counter

⚠ _DamageSkinService:Play is in the Client space — to call it from server logic (HP subtraction, etc.) wrap it in an @ExecSpace("Client") method or change a @Sync property and trigger from OnSyncProperty.

⚠ `Play()` has 6 required parameters. Passing only some of the 5 optional ones triggers LEA-3005 `InvalidArgument`.

11-3. Recipes

(a) Critical emphasis — auto mode + dynamic scale

Auto mode renders red font automatically when IsCritical=true. To emphasize further, temporarily increase the attacker-side scale:

-- ⚠ AttackComponent hooks (CalcDamage/CalcCritical/GetCriticalDamageRate/GetDisplayHitCount/
--   IsAttackTarget/IsHitTarget/OnAttack) have an unspecified ExecSpace (=All) on the parent.
--   Adding @ExecSpace when overriding triggers LEA-3014 SignatureMismatch.
--   Details: msw-scripting/SKILL.md §9 "Method override → LEA-3014"
method integer CalcDamage(Entity attacker, Entity defender, string attackInfo)
    return 100
end

method boolean CalcCritical(Entity attacker, Entity defender, string attackInfo)
    return math.random() < 0.3
end

method float GetCriticalDamageRate()
    return 2.5     -- 100 → 250
end

Differentiate criticals visually with DamageSkinSettingComponent.TweenType = Volcano (fan scatter) or Blade (overlap).

(b) Heal / recovery — manual call

local HEAL_RUID = "d58b67cf0f3a4eaf9fe1ad87c0ffac8a"

@ExecSpace("Client")
method void ShowHeal(Entity target, integer amount)
    _DamageSkinService:Play(
        target, HEAL_RUID, 0,
        { amount },                            -- damages
        DamageSkinTweenType.Default,
        false,                                 -- isCritical
        Vector2(0, 0.5),                       -- offset (above head)
        Vector2(1, 1), 1.0, 1.0, LitMode.Default
    )
end

(c) Miss / Guard / Resist text

local HIT_RUID = "02c22d93421b4038b3c413b3e40b57ec"

@ExecSpace("Client")
method void ShowMiss(Entity target)
    _DamageSkinService:PlayTextDamage(
        target, HIT_RUID, DamageSkinTextType.Miss, DamageSkinTweenType.Default
    )
end

Call this when AttackComponent:IsAttackTarget returned false → "miss animation + damage 0".

(d) Multi-hit — split into N with a single call

If you pass a List as the damages argument of _DamageSkinService:Play, the numbers are shown sequentially at DelayPerAttack (attacker component value) intervals:

_DamageSkinService:Play(target, ATTACK_RUID, 0, { 12, 8, 14, 11, 9 },
    DamageSkinTweenType.Default, false, Vector2(0,0), Vector2(1,1), 1, 1, LitMode.Default)

Auto mode behaves identically with HitEvent.Damages (List) — override GetDisplayHitCount(attackInfo) to control the split count.

(e) Preload — prevent first-display stutter

The first use of a skin RUID may have texture loading lag. Preload on map entry:

@ExecSpace("ClientOnly")
method void OnBeginPlay()
    _DamageSkinService:PreloadAsync("3271c3e79bf04ecba9a107d55495970d", function(ok) end)
    _DamageSkinService:PreloadAsync("02c22d93421b4038b3c413b3e40b57ec", function(ok) end)
    _DamageSkinService:PreloadAsync("d58b67cf0f3a4eaf9fe1ad87c0ffac8a", function(ok) end)
end

(f) TweenType use cases

(g) Faction-specific skins

To use different skin RUIDs per side (player vs enemy, PvP factions, etc.), swap DamageSkinSettingComponent.DamageSkinId at runtime:

self.Entity.DamageSkinSettingComponent.DamageSkinId = MY_TEAM_SKIN_RUID

---

12. Hit effect — HitEffectSpawnerComponent

Attach to the defender and a hit effect plays automatically on HitEvent. No properties — just add the component to the .model.

---

13. Full combat checklist

• [ ] Attacker model: an AttackComponent-derived script (+ optional: DamageSkinSettingComponent)
• [ ] Defender model: HitComponent + HitEffectSpawnerComponent + (optional: DamageSkinSpawnerComponent + DamageSkinComponent)
• [ ] HitComponent: IsLegacy=false, set ColliderType/BoxSize/CircleRadius, set CollisionGroup
• [ ] State motions: register ATTACK/HIT/DEAD in StateComponent + AvatarStateAnimationComponent.StateToAvatarBodyActionSheet
• [ ] HP handling: player uses PlayerComponent.Hp; monster uses custom @Sync Hp
• [ ] Direction check: LookDirectionX (no Scale.x)
• [ ] Time reference: _UtilLogic.ElapsedSeconds (no os.clock)
• [ ] Event cleanup: explicit DisconnectEvent in OnEndPlay
• [ ] Body rule: do not assign TransformComponent.Position directly on an entity with an active Body

---

14. Custom implementation is required

Buff/Debuff · BT Decorator/Memory(Blackboard) · Aggro/Threat Table · projectile pooling · pierce/max-hits · stagger-level system · resources (MP/Stamina/Rage) · combo/cancel windows · guard/parry · world→screen coordinate conversion · worldspace HP bar

---

Out of scope

• General player topics (HP/movement/camera/costume aside): `msw-defaultplayer`
• General mlua grammar/lifecycle: `msw-scripting`
• .model authoring rules/templates: `msw-general`

AI BehaviourTree — AIComponent + Composite/Action Node

0. When to use BT

MSW supports both paradigms natively. Use BT for multi-layer decision making and reusable action modules.

Code-based BT vs data-based BT — pick one per `AIComponent`. This reference covers the code-based path: @BTNode mlua scripts assembled at runtime via AIComponent:CreateNode / SetRootNode. The data-based path is a separate .behaviourtree JSON file edited in the Maker editor with definitionId wiring — that pipeline has its own authoring rules and lives in the `msw-behaviourtree` sibling skill. The two pipelines do not mix on the same AIComponent; if a project already has .behaviourtree assets, use msw-behaviourtree instead of this reference.

---

1. AIComponent API

@Component AIComponent
  property boolean IsLegacy = false                 -- fixed false (legacy deprecated)
  property boolean LogEnabled = false               -- BT execution log in Maker mode
  property UpdateAuthorityType UpdateAuthority = UpdateAuthorityType.Server

  method BTNode CreateLeafNode(string nodeName, func(float) -> BehaviourTreeStatus onBehave)
  method BTNode CreateNode(string nodeType, string nodeName = nil, func(float) -> BehaviourTreeStatus = nil)
  method void   SetRootNode(BTNode node)

BehaviourTreeStatus:

---

2. Four Composite Nodes (native)

Common methods (all Composites, 1-indexed)

method void    AttachChild(BTNode node)
method void    AttachChildAt(BTNode node, int32 index)
method boolean DetachChild(BTNode node | string nodeName)
method void    DetachChildAt(int32 index)

Extra methods on RandomSelectorNode

method void    AttachChild(BTNode node, number probability)        -- 0~1
method boolean SetChildNodeProbability(BTNode node, number probability)

---

3. Action Node — user-defined via @BTNode

The source annotation and the Maker UI menu name differ. The only annotation written in the mlua source is @BTNode. Confusing it with the "Create BTNodeType" menu name in the Maker UI and writing @BTNodeType passes the build (info-level) but does not generate the `.codeblock` → CreateNode("ActionWait", ...) returns nil → [LEA-2007] AttemptToIndex.

>

`extends BTNode` is required. Inheritance is what activates the Behave/ParentAI/Name members.

Lifecycle

Two ways to create

(a) `CreateNode` — based on a `@BTNode` script (reusable)

@BTNode
script ActionWait extends BTNode
    property number Time = 2
    property number ElapsedTime = 0

    method void OnInit()
        self.ElapsedTime = 0
    end

    method any OnBehave(number delta)
        self.ElapsedTime += delta
        if self.ElapsedTime < self.Time then
            return BehaviourTreeStatus.Running
        end
        return BehaviourTreeStatus.Success
    end
end

local waitNode = self.Entity.AIComponent:CreateNode("ActionWait", "wait1")

(b) `CreateLeafNode` — inline function (one-off)

local logNode = self.Entity.AIComponent:CreateLeafNode("printLog", function(delta)
    log("Action!")
    return BehaviourTreeStatus.Success
end)

⚠ Engine enums cannot cross execution spaces via `any`. Boss/monster Action Nodes commonly broadcast a particle / effect from server logic via an @ExecSpace("Client") helper. Passing an engine enum (BasicParticleType.SparkRadialExplosion, etc.) through an any parameter triggers [LEA-3036] InvalidCast on the first call, and declaring the parameter with the enum type itself is rejected by mlua diagnostics. Encode the enum as a string key and branch on the receiver:

>

```lua

@ExecSpace("Client")

method void BroadcastParticle(string particleKey, Vector3 pos)

if particleKey == "spark_radial" then

_ParticleService:PlayBasicParticle(BasicParticleType.SparkRadialExplosion, self.Entity, pos, 0, Vector3(1,1,1), false, nil)

elseif particleKey == "charge" then

_ParticleService:PlayBasicParticle(BasicParticleType.Charge, self.Entity, pos, 0, Vector3(1,1,1), false, nil)

end

end

```

>

Same rule for @ExecSpace("Server" | "Multicast") parameters that carry enum values — declare them as string and decode in the receiver.

---

4. Decorator Node — custom (not native)

Conditional child execution, result inversion, repetition, etc. Standard pattern:

@BTNode
script DecoInverter extends BTNode
    property any Child = nil

    method any OnBehave(number delta)
        if self.Child == nil then return BehaviourTreeStatus.Failure end
        local r = self.Child:Behave(delta)
        if r == BehaviourTreeStatus.Success then return BehaviourTreeStatus.Failure end
        if r == BehaviourTreeStatus.Failure then return BehaviourTreeStatus.Success end
        return BehaviourTreeStatus.Running
    end
end

---

5. Memory (Blackboard) — custom (not native)

A shared state channel between Action Nodes. `BTNode.ParentAI` references the AIComponent that owns this tree → the access path to memory.

@Component
script AIPatrolComponent extends AIComponent
    property table Memory = {}

    @ExecSpace("ServerOnly")
    method void SetMemory(string key, any value)
        self.Memory[key] = value
    end

    @ExecSpace("ServerOnly")
    method any GetMemory(string key)
        return self.Memory[key]
    end
end

-- Inside an Action Node:
method any OnBehave(number delta)
    local parentAI = self.ParentAI       -- BTNode's ParentAI property
    local target = parentAI:GetMemory("PlayerInRange")
    if target == nil then return BehaviourTreeStatus.Failure end
    -- target chase logic
    return BehaviourTreeStatus.Running
end

---

6. Tree assembly — standard pattern

@ExecSpace("ServerOnly")
method void OnBeginPlay()
    -- 1. Create Composites
    local root     = SelectorNode("root")
    local chaseSeq = SequenceNode("chase")
    local idleSeq  = SequenceNode("idle")

    -- 2. Create Actions
    local hasTarget = self:CreateNode("DecoHasTarget",   "hasTarget")
    local follow    = self:CreateNode("ActionFollow",    "follow")
    local noTarget  = self:CreateNode("DecoHasNoTarget", "noTarget")
    local wander    = self:CreateNode("ActionMoveRandom","wander")
    local wait      = self:CreateNode("ActionWait",      "wait")

    -- 3. Wire (left→right = high→low priority)
    chaseSeq:AttachChild(hasTarget)
    chaseSeq:AttachChild(follow)
    idleSeq:AttachChild(noTarget)
    idleSeq:AttachChild(wander)
    idleSeq:AttachChild(wait)
    root:AttachChild(chaseSeq)
    root:AttachChild(idleSeq)

    -- 4. Register root → runs automatically every frame
    self:SetRootNode(root)
end

Each frame traverses from the root left→right, top→bottom. Children that return Running are re-run by the parent next frame, starting from that child.

---

7. Running semantics — essentials

• Child returns Running → the parent re-runs from that child next frame (if the first child of a Sequence returns Running, the second is not called)
• Parallel exception: every child runs every frame; children that already returned Success/Failure are skipped
• OnInit() is not called the next frame after Running → accumulated time/state is preserved

---

8. Native BT components — AIChaseComponent / AIWanderComponent

Usable immediately without writing your own BT. Both have CreateLeafNode/CreateNode/SetRootNode → native chase/wander can be mixed with custom BT nodes.

⚠ Velocity conflict: AIChaseComponent/AIWanderComponent call MovementComponent.MoveToDirection → Body.SetVelocity every frame. When used alongside a custom chase script, they overwrite the velocity. Remove both from the `.model` when using custom AI. The two cannot coexist.

---

9. Threat / Aggro Table — custom (Memory pattern extension)

@ExecSpace("ServerOnly")
method void AddThreat(Entity attacker, number amount)
    local t = self:GetMemory("ThreatTable") or {}
    t[attacker] = (t[attacker] or 0) + amount
    self:SetMemory("ThreatTable", t)
end

method Entity GetTopThreat()
    local t = self:GetMemory("ThreatTable") or {}
    local best, max = nil, 0
    for ent, v in pairs(t) do
        if v > max then best, max = ent, v end
    end
    return best
end

In HandleHitEvent, call AddThreat(event.AttackerEntity, event.TotalDamage) → the BT chase node uses GetTopThreat() to pick priorities.

---

10. Checklist

• [ ] Custom Action/Decorator scripts have both `@BTNode` and `extends BTNode` (@BTNodeType builds but does not generate the .codeblock)
• [ ] After refresh, a .codeblock with the same name exists next to the custom BTNode .mlua — if missing, the annotation or extends is missing
• [ ] If CreateNode("XXX", ...) returns nil, [LEA-2007] AttemptToIndex follows → check annotation and extends
• [ ] AIComponent.IsLegacy = false (legacy deprecated)
• [ ] Keep UpdateAuthority = Server (same space as a custom chase script)
• [ ] Every Action Node OnBehave returns a BehaviourTreeStatus
• [ ] Be aware of Running semantics — when a Sequence's first child Runs, the second is not called
• [ ] When using custom BT, remove AIChaseComponent/AIWanderComponent from the .model
• [ ] Access the Memory table only through @ExecSpace("ServerOnly") methods (to prevent RPC leakage)
• [ ] DisconnectEvent external event handlers in OnEndPlay

HP gauge — PixelRendererComponent + Lazy Init

All PixelRendererComponent methods are @ExecSpace("ClientOnly") — the buffer init and per-pixel writes must run on the client.

---

Why PixelRendererComponent

Alternative ways to attach a health bar to a dynamically spawned entity, and their failure cases:

PixelRendererComponent is a native component — it can be included in .model directly, without the missing-.codeblock silent-drop risk that custom scripts have.

---

Flow

Server: HP/MaxHP change (@Sync)
  └→ Client: OnSyncProperty("HP"/"MaxHP") detected
       └→ UpdateHealthBar() — paint via SetPixel
Client OnUpdate: check PixelRenderer readiness → InitHealthBar() (lazy init)

---

Step 1: Add PixelRendererComponent to the model

Add the following component to the .model:

Setting SortingLayer at runtime:

-- Inside InitHealthBar
pixel.SortingLayer = "MapLayer0"
pixel.OrderInLayer = 10    -- Higher than the monster SpriteRenderer (OrderInLayer=2)

---

Step 2: Script — @Sync HP/MaxHP + full HP gauge template

@Component
script MonsterAI extends Component

    @Sync
    property number HP = 100

    @Sync
    property number MaxHP = 100

    -- Client: initialize the pixel buffer (Lazy Init)
    -- Why Lazy Init: for dynamically spawned entities the PixelRendererComponent
    -- may not be ready on the client at OnBeginPlay time
    @ExecSpace("ClientOnly")
    method void InitHealthBar()
        local pixel = self.Entity.PixelRendererComponent
        if pixel == nil then return end
        -- 16×3: 16 px wide (HP steps), 3 px tall (thickness)
        -- SetPixel coordinate system: bottom-left (1,1) origin
        pixel:ResetWithColor(16, 3, Color(0, 1, 0, 1))
        pixel.SortingLayer = "MapLayer0"
        pixel.OrderInLayer = 10
        self._T.hpBarPixel   = pixel
        self._T.hpBarInited  = true
        self:UpdateHealthBar()
    end

    -- Client: paint pixels based on HP ratio
    @ExecSpace("ClientOnly")
    method void UpdateHealthBar()
        if not self._T.hpBarInited then return end
        local pixel = self._T.hpBarPixel
        if pixel == nil then return end

        local ratio = 0
        if self.MaxHP > 0 then
            ratio = math.max(0, self.HP / self.MaxHP)
        end
        local fillWidth = math.max(0, math.floor(ratio * 16))

        -- Color thresholds: >60% → green, 31~60% → yellow, 0~30% → red
        local barColor
        if ratio <= 0.3 then
            barColor = Color(1, 0, 0, 1)
        elseif ratio <= 0.6 then
            barColor = Color(1, 1, 0, 1)
        else
            barColor = Color(0, 1, 0, 1)
        end

        for x = 1, 16 do
            for y = 1, 3 do
                if x <= fillWidth then
                    pixel:SetPixel(x, y, barColor)
                else
                    pixel:SetPixel(x, y, Color(0.2, 0.2, 0.2, 0.8))
                end
            end
        end
    end

    -- @Sync property change detection → refresh the bar
    @ExecSpace("ClientOnly")
    method void OnSyncProperty(string name, any value)
        if name == "HP" or name == "MaxHP" then
            self:UpdateHealthBar()
        end
    end

    -- OnUpdate: no @ExecSpace → runs on both server and client
    -- Branch via IsClient()/IsServer() (health bar on client, combat logic on server)
    method void OnUpdate(number delta)
        if self:IsClient() then
            if self._T.hpBarInited == nil then self._T.hpBarInited = false end
            if not self._T.hpBarInited then
                self:InitHealthBar()
            end
        end

        if not self:IsServer() then return end
        -- Server-only logic (AI, death handling, etc.)
    end

    @EventSender("Self")
    @ExecSpace("ServerOnly")
    handler HandleHitEvent(HitEvent event)
        self.HP -= event.TotalDamage
        if self.HP <= 0 then
            self.HP = 0
            self.Entity.StateComponent:ChangeState("DEAD")
            -- Death handling is in a separate DeadEvent handler
        end
    end

    method void OnEndPlay()
        self.Entity:DisconnectEvent(HitEvent, self.HandleHitEvent)
    end

end

---

PixelRendererComponent API summary

-- Buffer init
@ExecSpace("ClientOnly") ResetWithColor(int32 width, int32 height, Color color)
@ExecSpace("ClientOnly") ResetWithColors(int32 width, int32 height, table<Color> pixels)

-- Pixel read/write  coordinates: bottom-left (1,1)
@ExecSpace("ClientOnly") SetPixel(int32 x, int32 y, Color color)
@ExecSpace("ClientOnly") GetPixel(int32 x, int32 y) → Color
@ExecSpace("ClientOnly") SetPixels(table<Color> pixels)   -- Width*Height in size
@ExecSpace("ClientOnly") GetPixels() → table<Color>

-- Fill all
@ExecSpace("ClientOnly") FillColor(Color color)
@ExecSpace("ClientOnly") SetAlpha(float alpha)

-- Properties
property int32  OrderInLayer = 0
property string SortingLayer = "Default"   -- For map entities, change to "MapLayer0"
property int32  Width  = 16   (read-only: set via ResetWithColor)
property int32  Height = 16

Recommended size: 16×N (N=2~4). Performance degrades above 16×16.

Width / Height are logical pixels of the texture grid, not screen pixels — the on-screen size scales with the entity's TransformComponent.Scale. Keep the logical grid small (16×3) and grow it visually through scale (e.g. Scale = (4, 4, 1)) instead of enlarging the grid.

---

Setting MaxHP on spawn

Include MonsterAI in the .model in advance (after Maker Refresh) → after spawn, only initialize HP/MaxHP via the handle:

@ExecSpace("ServerOnly")
method void SpawnMonster(Vector3 pos)
    local parent = self.Entity.CurrentMap
    local entity = _SpawnService:SpawnByModelId(
        "monster_1_model", "monster_1", pos, parent  -- 1st arg: the .model's EntryKey, case-insensitive
    )
    local ai = entity.MonsterAI
    if ai ~= nil then
        ai.HP    = 100
        ai.MaxHP = 100
    end
end

---

Constraints

Projectile system — ProjectileComponent + SpawnByModelId

Attack Resolution basics and per-Body knockback live in `msw-combat-system/SKILL.md` §1·§3.

---

Core architecture

Why a separate entity

A projectile has an independent lifecycle (spawn → move → hit → destroy), so separating it from the firing unit into its own entity is the standard MSW pattern.

Projectile model composition (no Body)

Hit detection comparison

When the target is already known → distance-based is the simplest.

Server / client responsibility split

@ExecSpace("ClientOnly"): ignored when called from the server. Always use "Client".

---

Step 1: Create the ProjectileComponent script

Create the .mlua under RootDesk/MyDesk/. (The .codeblock is auto-generated after Maker Refresh.)

@Component
script ProjectileComponent extends Component

    property number Speed = 10          -- movement speed
    property number Damage = 10         -- damage on hit
    property number MaxLifetime = 3     -- auto-destroy time (seconds)
    property string HitEffectRUID = ""  -- hit effect RUID
    property number HitRadius = 0.5     -- hit distance threshold
    property string EnemyModelId = ""   -- enemy scan model id (straight projectile)

    method void OnBeginPlay()
        self._T.fired = false
        self._T.lifetime = 0
        self._T.dirX = 0
        self._T.dirY = 0
    end

    -- Fire: compute target direction, set fired=true
    @ExecSpace("ServerOnly")
    method void Fire(Entity target)
        self._T.target = target
        if target ~= nil and isvalid(target) then
            local myPos = self.Entity.TransformComponent.Position
            local tPos  = target.TransformComponent.Position
            local dx = tPos.x - myPos.x
            local dy = tPos.y - myPos.y
            local dist = math.sqrt(dx*dx + dy*dy)
            if dist > 0 then
                self._T.dirX = dx / dist
                self._T.dirY = dy / dist
            else
                self._T.dirX = 1
                self._T.dirY = 0
            end
        end
        self._T.fired = true
    end

    -- Movement + homing + hit detection
    @ExecSpace("ServerOnly")
    method void OnUpdate(number delta)
        if not self._T.fired then return end

        self._T.lifetime = self._T.lifetime + delta
        if self._T.lifetime >= self.MaxLifetime then
            _EntityService:Destroy(self.Entity)
            return
        end

        if self._T.target ~= nil and isvalid(self._T.target) then
            local myPos = self.Entity.TransformComponent.Position
            local tPos  = self._T.target.TransformComponent.Position
            local dx = tPos.x - myPos.x
            local dy = tPos.y - myPos.y
            local dist = math.sqrt(dx*dx + dy*dy)

            -- Hit
            if dist <= self.HitRadius then
                self:OnHit()
                return
            end

            -- Homing: recompute direction each frame (remove this block for straight projectiles)
            if dist > 0 then
                self._T.dirX = dx / dist
                self._T.dirY = dy / dist
            end
        end

        -- Move — for a Body-less entity, use Translate (§1-6)
        self.Entity.TransformComponent:Translate(
            self._T.dirX * self.Speed * delta,
            self._T.dirY * self.Speed * delta
        )
    end

    -- Hit handling (server)
    -- ⚠ Do not subtract HP directly — bypassing HitEvent skips damage skin / hit effect / IsHitTarget immunity entirely.
    --   Details: msw-combat-system/SKILL.md §2-3
    -- Recommended: add an AttackComponent-derived script to the projectile model → fire an ad-hoc hitbox via AttackFrom
    @ExecSpace("ServerOnly")
    method void OnHit()
        local pos = self.Entity.TransformComponent.Position      -- Vector3
        local ac = self.Entity.AttackComponent
        if ac ~= nil then
            ac:AttackFrom(
                Vector2(self.HitRadius * 2, self.HitRadius * 2),  -- hitbox size (Vector2)
                pos:ToVector2(),                                  -- hit position (Vector2 — AttackFrom takes Vector2, not Vector3)
                "projectile",                                     -- attackInfo
                CollisionGroups.Monster
            )
        end
        -- Preserve coordinates before destruction and call the effect (so it persists after entity destruction)
        self:ShowHitEffect(pos.x, pos.y, pos.z)
        _EntityService:Destroy(self.Entity)
    end

    -- Hit effect (client)
    -- Use PlayEffect (fixed coordinates): the effect keeps playing even after the entity is destroyed
    -- PlayEffectAttached (attached to the entity) disappears when the entity is destroyed
    @ExecSpace("Client")
    method void ShowHitEffect(number px, number py, number pz)
        if self.HitEffectRUID == "" then return end
        local mapEntity = self.Entity.CurrentMap
        if mapEntity == nil then return end
        _EffectService:PlayEffect(
            self.HitEffectRUID, mapEntity,
            Vector3(px, py, pz), 0, Vector3(1, 1, 1), false
        )
    end

    method void OnEndPlay()
        -- _T is cleaned up by the engine, no manual release needed
    end

end

---

Step 2: Create the projectile model

After writing the .mlua, run Maker Refresh once → ProjectileComponent.codeblock is auto-generated. Then include the following in the .model:

ProjectileAttackComponent (or an equivalent script) must be included for damage skin / hit effect / i-frame to work. Bypassing with simple ai.HP -= damage is wrong — see `msw-combat-system/SKILL.md` §2-3.

Projectile sprite search:

msw-search → resource search: "energy ball", "arrow", "fireball" / type: sprite / category: skill

---

Step 3: Spawn + fire

Since ProjectileComponent is already included in the .model, use the component handle directly after SpawnByModelId.

-- SpawnService.d.mlua
_SpawnService:SpawnByModelId(string id, string name, Vector3 spawnPosition, Entity parent) → Entity

@ExecSpace("ServerOnly")
method void FireProjectile(Entity target)
    local parent = self.Entity.CurrentMap
    if parent == nil then return end

    -- Unique name (collision prevention)
    if self._T.projCount == nil then self._T.projCount = 0 end
    self._T.projCount = self._T.projCount + 1
    local name = "proj_" .. tostring(self._T.projCount)

    local myPos = self.Entity.TransformComponent.Position
    local proj = _SpawnService:SpawnByModelId(
        self._T.projectileModelId,     -- the .model's EntryKey (case-insensitive), not a URL
        name,
        Vector3(myPos.x, myPos.y, myPos.z),
        parent
    )
    if proj == nil then return end

    -- ProjectileComponent is already in the .model → just receive the handle and configure
    local pc = proj.ProjectileComponent
    if pc == nil then return end
    pc.Speed    = 10
    pc.Damage   = self.Damage
    pc.HitRadius = 0.5
    pc.HitEffectRUID = "<hit effect RUID>"
    pc:Fire(target)
end

Obtaining the parent entity

self.Entity.CurrentMap                                  -- current map entity (recommended)
_EntityService:GetEntityByPath("/maps/MapName")          -- explicit path

---

Step 4: Wire into the firing unit (melee ↔ ranged branch)

@ExecSpace("ServerOnly")
method void TryAttack()
    if self._T.target == nil or not isvalid(self._T.target) then return end
    if self._T.atkTm < self.AttackCooldown then return end
    self._T.atkTm = 0

    if self.UseProjectile then
        self:FireProjectile(self._T.target)
    else
        -- Direct melee hit
        local ac = self.Entity.AttackComponent
        if ac ~= nil then
            ac:Attack(Vector2(1.5, 1.0), Vector2(0, 0), "melee", CollisionGroups.Monster)
        end
    end
end

---

Variants

Straight projectile (no homing)

Remove the direction-recompute block in OnUpdate. Instead scan for enemies ahead via EnemyModelId:

-- Replace the homing block in OnUpdate with:
local enemies = _EntityService:GetEntitiesSpawnedByModelId(self.EnemyModelId)
if enemies ~= nil then
    for _, enemy in pairs(enemies) do
        if isvalid(enemy) then
            local ep = enemy.TransformComponent.Position
            local pos = self.Entity.TransformComponent.Position
            local dx = pos.x - ep.x
            local dy = pos.y - ep.y
            if math.sqrt(dx*dx + dy*dy) <= self.HitRadius then
                self._T.target = enemy
                self:OnHit()
                return
            end
        end
    end
end
self.Entity.TransformComponent:Translate(
    self._T.dirX * self.Speed * delta,
    self._T.dirY * self.Speed * delta
)

Pierce projectile

Remove Destroy in OnHit, prevent duplicates with hitList. Damage goes through AttackFrom + check the hitList in an attacker-side IsAttackTarget override:

@ExecSpace("ServerOnly")
method void OnHit()
    if self._T.hitList == nil then self._T.hitList = {} end

    local pos = self.Entity.TransformComponent.Position          -- Vector3
    local ac = self.Entity.AttackComponent
    if ac ~= nil then
        ac:AttackFrom(
            Vector2(self.HitRadius * 2, self.HitRadius * 2),
            pos:ToVector2(), "projectile.pierce", CollisionGroups.Monster  -- AttackFrom takes Vector2
        )
    end

    self:ShowHitEffect(pos.x, pos.y, pos.z)
    -- Do not call Destroy → pierce
end

Block duplicate hits in ProjectileAttackComponent:

-- ⚠ AttackComponent.IsAttackTarget has an unspecified ExecSpace (=All) on the parent.
--   Adding @ExecSpace to the override triggers LEA-3014 SignatureMismatch.
--   Details: msw-scripting/SKILL.md §9 "Method override"
method boolean IsAttackTarget(Entity defender, string attackInfo)
    local proj = self.Entity.ProjectileComponent
    if proj == nil then return __base:IsAttackTarget(defender, attackInfo) end
    if proj._T.hitList == nil then proj._T.hitList = {} end
    local id = defender.Name
    if proj._T.hitList[id] then return false end
    proj._T.hitList[id] = true
    return __base:IsAttackTarget(defender, attackInfo)
end

Area explosion (AOE)

@ExecSpace("ServerOnly")
method void OnHit()
    local pos = self.Entity.TransformComponent.Position          -- Vector3
    local blastRadius = 2.0
    local ac = self.Entity.AttackComponent
    if ac ~= nil then
        -- Circular AoE in one call — Shape-based Attack (CircleShape takes Vector2)
        ac:Attack(CircleShape(pos:ToVector2(), blastRadius), "projectile.aoe", CollisionGroups.Monster)
    end
    self:ShowHitEffect(pos.x, pos.y, pos.z)
    _EntityService:Destroy(self.Entity)
end

---

Constraints