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".

• The cg argument of Attack*(..., cg) is an exact-match filter on the defender's `HitComponent.CollisionGroup` (defaults to CollisionGroups.HitBox). It does not consult the collision matrix, and the attacker's own group is irrelevant. nil (omitted) = every HitComponent is a candidate. A valid group that differs from the defenders' actual group hits 0 targets with no error (silent); a group reference that does not exist in this world's collision group set behaves like nil (all groups). When passing a group (e.g. CollisionGroups.Monster), first set the target monsters' HitComponent.CollisionGroup to that same group — the sample workspace monsters override it to Monster, which is why the sample attack scripts work. A model imported from another world whose group id is missing from this world's set silently registers under the Default group — reach it with nil or CollisionGroups.Default.
• 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