Readable layout
---
name: msw-scripting
description: "Authoring MSW scripts (.mlua) plus integrated playtest and debugging. Covers mlua syntax, annotations (@Component/@Logic/@ExecSpace/@Sync), lifecycle, exec spaces, property sync, event system, file workflow, build-log inspection, error classification, and the test/debug loop. Keywords: script, mlua, lua, Component, Logic, annotation, ExecSpace, Sync, event, play, test, debug, lifecycle."
---
# MSW Scripting (.mlua) — Framework + File Workflow + Playtest & Debugging
mlua is Lua-based, but it has MSW-specific annotations, a lifecycle, and an execution-space model.
General Lua knowledge alone will not produce working code. All work is done by **editing files in the workspace directly**,
and code is validated in the order **build logs → runtime logs**.
---
## 1. Core Principles (must follow)
### 1.1 Existing Script First
Before creating a new `.mlua`, glob/keyword-search under `./RootDesk/MyDesk/` for an existing script with the same purpose — **extending an existing file is always the first choice**. Duplicate implementations raise maintenance cost and conflict risk.
### 1.2 Folder Structure for New Scripts — Never Dump Files Flat
When a new `.mlua` is unavoidable, place it under a feature/category subfolder. **Required path shape**: `./RootDesk/MyDesk//.mlua`.
- **Reuse** an existing subfolder if it fits (`Player/`, `UI/`, `Combat/`, `Inventory/`, …); glob `./RootDesk/MyDesk/` first.
- **Otherwise create** one named for the feature (PascalCase). All related scripts of one feature (Component/Logic/Event/Struct) stay together. Even a single-file feature gets its own folder.
- **Forbidden**: catch-all folders like `Scripts/`, `Misc/`, `Common/`, `New/`, `temp/`. A flat root makes rule §1.1 (search before creating) impossible.
Examples: `Inventory/InventoryManager.mlua`, `Combat/MeleeAttackComponent.mlua`, `UI/Popup/RewardPopupLogic.mlua`.
### 1.3 Never Guess APIs — Verify Before Writing
Guessing an MSW API name/param/return type **silently fails at runtime**. Required order: **`.d.mlua` for signature** → **`msw-search` for semantics/examples** if needed → write → LSP diagnose (auto-run).
The engine API lives under `./Environment/NativeScripts/`:
| Folder | Contents | Count |
|------|------|:-:|
| `Component/` | Engine components | 104 |
| `Service/` | System services | 46 |
| `Event/` | Event types | 202 |
| `Logic/` | Built-in logic | 9 |
| `Enum/` | Enumerations | 118 |
| `Misc/` | Utility types (Vector2, …) | 140 |
Known name → `Read ./Environment/NativeScripts/{folder}/{name}.d.mlua`. Unknown name → Grep keywords there.
### 1.4 Lint (LSP diagnostics)
`mlua-diagnose` hook runs LSP `diagnose` automatically after every `.mlua` create/modify. Iterate fix → re-edit until error-severity diagnostics reach zero.
### 1.5 `.codeblock` & Refresh
- `.codeblock` files are generated by Maker Refresh — never create/edit/delete manually.
- After any `.mlua` create/modify/rename/delete, call Maker MCP **`refresh`**. Refresh requires edit mode — `stop` first if playing.
### 1.6 MSW ≠ Unity — Do Not Reason From Intuition
Applying Unity/generic patterns directly **compiles fine but silently fails at runtime**. Common misconceptions:
| Unity intuition | MSW reality / Where it's covered |
|---|---|
| `gameObject` / `transform` from a global manager | `@Logic` has no `self.Entity` — see §3.2 (use property injection / `_EntityService`) |
| `OnMouseDown` / `BoxCollider2D` for clicks | Physics colliders never emit `TouchEvent` — World uses `TouchReceiveComponent` (§10); UI uses `ButtonComponent`/`UITouchReceiveComponent` |
| `OnCollisionEnter` + Rigidbody | Entity↔entity collisions need `TriggerComponent` + `TriggerEnter/Leave/Stay` event |
| UI field names (`interactable`/`text`/`color`) | MSW-specific names — check [`msw-ui-system/references/component-api.md`](../msw-ui-system/references/component-api.md). Common mappings: disable→`Enable`, text→`Text`, text color→`FontColor`, tint→`Color`. `ButtonComponent.Interactable` doesn't exist. |
| Attach multiple Rigidbody/Collider freely | **One Body per map type** — see [`msw-general/references/platform.md`](../msw-general/references/platform.md) §4 |
| Touch UI from server code | **UI is client-only** — server→UI goes via `@ExecSpace("Client")` RPC. Hosting `Server`/`ServerOnly`/`Multicast`/`@Sync` on a UI-attached Component silently no-ops with runtime warning. See [`msw-ui-system/references/runtime-patterns.md`](../msw-ui-system/references/runtime-patterns.md) |
| `Instantiate(prefab)` callable anywhere | `_SpawnService:SpawnByModelId(id, name, pos, parent)` — `parent` required, server-only — see §11 |
| `static` classes / hand-rolled singletons | `@Logic` is itself the singleton — call as `_ScriptName:Method()`, never instantiate — see §3.2 |
**Rule**: when tempted to apply a Unity pattern, stop and verify against `Environment/NativeScripts/*.d.mlua` first.
### 1.7 Builder Protocol Preflight — **MUST**
If this turn touches `.map` / `.model` / `.ui` (directly, or via spawn/entity-placement/UI-binding code in `.mlua`), **[`../msw-general/references/builder-protocol.md`](../msw-general/references/builder-protocol.md) (core) plus the per-builder file for each type touched ([`builder-protocol-map.md`](../msw-general/references/builder-protocol-map.md) / [`builder-protocol-model.md`](../msw-general/references/builder-protocol-model.md) / [`builder-protocol-ui.md`](../msw-general/references/builder-protocol-ui.md)) must be fully in context first** (`Read` the full files only if never loaded this session or lost to compaction — a memorized summary does not count as in context). The core carries the shared write-side contract and cross-flow; each per-builder file carries that builder's API, `typeKey` metadata, auto-lint, child-entity invariants, and `placeModel` mirroring; knowing one builder doesn't cover another.
**Triggers** (broad on purpose): `_SpawnService` / `SpawnByModelId` / `SpawnByEntity`; any `.map`/`.model`/`.ui` change; calling `msw_map_builder.cjs` / `msw_model_builder.cjs` / `msw_ui_builder.cjs`; any "new monster/NPC/popup/map object" request; §11 or §16 work.
### 1.8 Method Documentation Comments — Inside the Body
Every `method` (lifecycle, RPC, event handler, user-defined) **must** have a description comment as the **first line inside the body**, never above the declaration. mlua's parser binds leading comments to the previous declaration, so an "above" comment is unreliable.
```lua
-- ✅ Correct
method void ApplyDamage(Entity target, number amount)
-- Applies damage and triggers hit VFX.
target:TakeDamage(amount)
end
-- ❌ Wrong — comment above the method
-- Applies damage...
method void ApplyDamage(Entity target, number amount)
target:TakeDamage(amount)
end
```
---
## 2. Paths and File Roles
| Target | Path | Agent action |
|------|------|----------------|
| User scripts | `./RootDesk/MyDesk/**/*.mlua` | **Create / read / modify / delete directly** |
| Auto-generated artifacts | `*.codeblock` | **Do not touch** (Refresh manages them) |
| Engine API definitions | `./Environment/NativeScripts/**` | **Read-only** (do not modify) |
| Models (component lists) | `./RootDesk/MyDesk/**/*.model` plus existing `./Global/*.model` files in place | Edit `Components` **when attaching scripts** |
| Map instances | `./map/*.map` | Edit when attaching scripts to entities that exist only inside a map |
---
## 3. Script Types and Declarations
### 3.1 Component scripts (`@Component`)
Scripts attached to an Entity. Use `self.Entity` to access the owning entity.
```lua
@Component
script MyScript extends Component
property number Speed = 5.0
@ExecSpace("ServerOnly")
method void OnBeginPlay()
-- initialization (also: OnUpdate(delta), OnEndPlay)
end
end
```
**Allowed parents**:
- `Component` — generic component
- `AttackComponent` — attack system (Shape, AttackFast, OnAttack)
- `HitComponent` — hit system (OnHit, HandleHitEvent)
### 3.2 Logic scripts (`@Logic`)
Global singletons. Run independently without an Entity. Use for game managers, UI managers, utilities, etc.
```lua
@Logic
script GameManager extends Logic
@Sync property integer Score = 0
@ExecSpace("ServerOnly")
method void OnBeginPlay()
-- global initialization (also: OnUpdate, OnEndPlay)
end
end
```
- One per world (singleton)
- Accessed as `_` — **no suffix stripping**. `TDHUDLogic.mlua` → `_TDHUDLogic` (not `_TDHUD`); `TowerDefenseConfig.mlua` → `_TowerDefenseConfig`. Heuristic stripping silently returns `nil`.
- Supports `@Sync` properties (server→client)
- Logic's `OnUpdate` runs **before** Components'.
> ⚠️ **`@Logic` has no `self.Entity`** — Logic parent only exposes `ConnectEvent`/`DisconnectEvent`/`IsClient`/`IsServer`/`SendEvent`. `self.Entity.xxx` compiles but is a runtime nil-access. To bind a world entity, inject via property (`property Entity x = "uuid"` / `property EntityRef x = ""`) or look it up with `_EntityService:GetEntityByPath(...)` / `:FindEntityByName(...)`. Property injection (UUID literal) is preferred. See §7.
>
> ⚠️ **`OnMapEnter` / `OnMapLeave` never fire on `@Logic`** — they're Component-only (see §5). Declaring them on a Logic is silent dead code. For per-map setup/cleanup either (1) move the behavior to a `@Component` on the map entity (preferred; the only option that works on the server), or (2) **client-side only**: poll `_UserService.LocalPlayer.CurrentMap` from `OnUpdate` — `LocalPlayer` is available only on the client (nil on the server). A Logic survives map transitions, so any timer / event handler / mutable state that should reset per map must be cleared via one of these — there is no automatic hook.
> **Decision: @Component vs @Logic — by lifetime, not "is it global?"**
>
> | Scope | Pick | Why |
> |---|---|---|
> | World-wide, survives every map transition (account state, world event bus, global UI manager) | **`@Logic`** | Engine singleton; lives for whole world session. |
> | **Map-scoped** — only meaningful inside one map (quest controller, wave spawner, puzzle) | **`@Component` on the map entity** | Cleaned on map unload. Putting this in `@Logic` leaks state/timers across maps. |
> | One actor (monster AI, item pickup, player skill) | **`@Component`** on that entity | |
>
> Ask: *"Still running after the player walks to another map?"* — Yes ⇒ `@Logic`; No (this map) ⇒ `@Component` on map entity; No (this actor) ⇒ `@Component` on actor.
### 3.3 Extend scripts
```lua
@Component
script PlayerAttack extends AttackComponent
-- Override parent methods; call parent via __base:MethodName()
end
```
### 3.4 Other script types
`@Event` (custom event) · `@Item` (inventory) · `@BTNode` (behaviour tree) · `@State` (state machine) · `@Struct` (composite data type).
---
## 4. mlua Language Extensions (vs. plain Lua)
Based on Lua 5.3 with these differences:
**Added syntax**:
- `continue` — skip to next loop iteration.
- Compound assignment: `+=`, `-=`, `*=`, `/=`, `//=`, `%=`, `^=`, `..=` (and bitwise `&=`, `|=`, `<<=`, `>>=`). Multi-assign (`a, b += 1, 2`) and use as a function arg (`print(a += 1)`) are invalid.
- Bitwise operators: `&`, `|`, `<<`, `>>`.
**Restrictions**:
- **No globals** (`global` keyword forbidden) — share values via Properties.
- **No coroutines** (`coroutine.*`).
- Parent call is `__base:MethodName()`, not `super`.
**Built-in utility functions**:
| Function | Purpose |
|------|------|
| `log()` / `log_warning()` / `log_error()` | Logging at each severity |
| `wait(seconds)` | Pause script execution |
| `isvalid(obj) → boolean` | Validity (handles deletion/nil) |
| `enum(t) → table` | Swap keys and values |
| `beginscope(name)` / `endscope()` | Profiling scopes |
---
## 5. Lifecycle
```
OnInitialize → OnBeginPlay → OnUpdate(delta) → OnEndPlay → OnDestroy
↑
OnMapEnter / OnMapLeave (Component only, per transition)
```
| Method | When | Where | Purpose |
|--------|------|------|------|
| `OnInitialize` | After creation | Component + Logic | Init internal vars (rarely used) |
| `OnBeginPlay` | Game start | Component + Logic | **Wire events, start timers, initial setup** |
| `OnUpdate(delta)` | Every frame | Component + Logic (**Logic first**) | Movement, animation, input |
| `OnMapEnter` / `OnMapLeave` | Map transition | **Component only** (silent no-op on Logic) | Per-map init/cleanup |
| `OnEndPlay` | Game end | Component + Logic | **Disconnect events, clear timers (mandatory!)** |
| `OnDestroy` | Removal | Component + Logic | Final cleanup (rarely used) |
On the client, `OnMapEnter` also fires for other players already in the map — not only for the local player's own entry.
**Required pattern**: everything connected in `OnBeginPlay` must be released in `OnEndPlay` (events, timers).
```lua
property any eventHandler = nil -- EventHandlerBase (must be 'any'; not integer)
property integer timerId = 0
method void OnBeginPlay()
self.eventHandler = self.Entity:ConnectEvent(SomeEvent, self.OnSomeEvent)
self.timerId = _TimerService:SetTimerRepeat(self.Tick, 1/60)
end
method void OnEndPlay()
if self.eventHandler then self.Entity:DisconnectEvent(SomeEvent, self.eventHandler) end
if self.timerId then _TimerService:ClearTimer(self.timerId) end
end
```
**`OnMapEnter` pairs with `OnMapLeave` — the map-transition timer leak.** `OnMapEnter` fires on **every** map re-entry, and a Component whose entity survives transitions (player, persistent objects) is **not** destroyed on leave — so a timer/handler started in `OnMapEnter` stacks one more live copy per re-entry. Clear it in `OnMapLeave`, not `OnEndPlay` (which fires only on final removal, so it never runs between transitions). A **repeating** timer (`SetTimerRepeat`, or `SetTimer(..., isRepeat = true)`) left registered is what the engine reports as `[LEA-3051] MemoryLeak` at the next play-mode start, naming the create line; once-timers (`SetTimerOnce`) self-clear after firing and are never flagged. Rule: whatever `OnMapEnter` starts, `OnMapLeave` must clear.
---
## 6. Execution Space (ExecSpace)
MSW is a server-client architecture. Every method must declare where it runs.
| ExecSpace | Runs on | Direction | Use case |
|-----------|----------|----------|------|
| `ServerOnly` | Server | Server-internal only | Damage calc, state changes, spawning |
| `ClientOnly` | Client | Client-internal only | UI updates, effects, sounds |
| `Server` | Server | Client→Server RPC | Client requesting the server (attack, item use) |
| `Client` | Client | Server→Client RPC | Server notifying a client (result UI, effects) |
| `Multicast` | All clients | Server→all clients | Global events (announcements, boss spawn) |
| *(unspecified)* | Caller side | Server→Server, Client→Client | Shared functions executed locally on either side |
### ExecSpace constraints on lifecycle methods
| Method | Allowed ExecSpace |
|--------|---------------|
| `OnSyncProperty` | **`ClientOnly` only** |
| `OnInitialize`, `OnBeginPlay`, `OnUpdate`, `OnEndPlay`, `OnDestroy`, `OnMapEnter`, `OnMapLeave` | `ServerOnly`, `ClientOnly`, or **unspecified** |
| All event handlers | `ServerOnly`, `ClientOnly`, or **unspecified** |
| Custom user methods | Any of `Server`, `Client`, `ServerOnly`, `ClientOnly`, `Multicast` |
### Typical server-client pattern
```
[Client] input (ClientOnly) ──Request()──→ [Server] validate (ServerOnly)
├─ state auto-syncs via @Sync
[Client] UI update (ClientOnly) ←──Show()──────┘ (Client RPC)
```
- `ServerOnly`: client call is silently ignored (no error).
- `Server`: client→server RPC (network latency).
- `Client`: server→client RPC; add UserId as the **last call-site arg** to target one client (do NOT add it to the declaration).
### `senderUserId` — verifying the requester
Inside an `@ExecSpace("Server")` body, the local `senderUserId` holds the caller client's UserId (server-assigned, not client-modifiable). Use it for security checks.
```lua
@ExecSpace("Server")
method void RequestBuyItem(integer itemId)
if senderUserId ~= self.Entity.PlayerComponent.UserId then return end
self:ProcessPurchase(itemId)
end
```
### Reserved parameter names — `name is unavailable`
Four parameter names are reserved for the RPC marshaller and cannot be used as your own parameter names on any `@ExecSpace(...)` method. The LSP blocks the script with `'' name is unavailable.`:
| Reserved | What the engine uses it for |
|---|---|
| `self` | Method receiver |
| `senderUserId` | Calling client's UserId on `@ExecSpace("Server")` bodies |
| `targetUserId` | Recipient client's UserId (last call-site arg on `@ExecSpace("Client")` bodies — do NOT declare it; the engine appends it) |
| `messageOwnerEntity` | Originating entity for some service callbacks |
Rename your own parameters when they collide (`targetUserId` → `forUserId`, `senderUserId` → `fromUserId`). `self` is the receiver and cannot be aliased — pick any other name for an unrelated parameter.
### Manual branching — `IsServer()` / `IsClient()` are **methods**, not properties
When a method has no `@ExecSpace` (runs on whichever side called it) and needs different paths per side, branch with `self:IsServer()` / `self:IsClient()`. Both are declared as `method boolean IsServer()` / `method boolean IsClient()` on `Component` and `Logic` — they must be **called**, not read.
```lua
if self:IsServer() then ... end -- ✅ method call → boolean
if self.IsServer then ... end -- ❌ method object itself → always truthy
```
The dot-without-parens form is a silent bug: the LSP doesn't flag it, the script compiles, and the "if" always enters because a method object is truthy — so client-only code runs on the server too (or vice versa). The symptom is "both branches execute on both sides," not a crash. Use colon-call (`self:IsServer()`) every time.
### Cross-boundary parameter types
Allowed across server↔client RPC: `string`, `integer`, `number`, `boolean`, `table`, `Vector2/3/4`, `Color`, `Entity`, `Component`, `EntityRef`, `ComponentRef`. **`any` not allowed.** Engine enums also do not cross — neither typed (the LSP rejects engine enum types as parameters) nor smuggled via `any` (runtime `LEA-3036 InvalidCast`). Standard workaround: encode the choice as a `string` key on the sender, branch on the receiver, and convert back to the enum locally. `SyncTable` generics must also be from the allowed list.
---
## 7. Property System
### Basic types
`number` (float/double — integers are separate type `integer`), `string`, `boolean`, `Vector2`/`Vector3`, `Color` (r,g,b,a in 0.0~1.0), `any`.
```lua
property number Speed = 5.0
property integer Count = 0
property Vector2 Direction = Vector2(0, 0)
property Color Tint = Color(1, 1, 1, 1)
```
### Entity / Component reference properties
```lua
property Entity targetEntity = "94a274e4-4111-40f1-924d-c95a3a1f14d5" -- UUID string literal
property ButtonComponent btnOk = "uuid-string" -- typed component ref
```
**AI must inject UUIDs directly** — read `id` from `.map`/`.ui` and hard-code as string literal. Never ask the user to drag-bind in the editor (that's a human-author convenience).
### Entity vs EntityRef
`Entity` / `Component` references are **dropped on map transition**. `EntityRef` / `ComponentRef` **survive** map transitions — prefer for multi-map games.
### Sync annotations
- `@Sync` — server → all clients. One-way; client-side change does NOT propagate back. Has network latency.
- `@TargetUserSync` — server → owning user's client only. Useful for per-player private data (currency, achievements). On a non-PlayerEntity it falls back to plain `@Sync`.
- **Cannot be synced**: `any`, `table` — use `SyncTable` instead.
- Both take no arguments.
```lua
@Sync property number CurrentHp = 100
@TargetUserSync property number PrivateScore = 0
@Sync property SyncTable Scores -- array form, NO default literal
@Sync property SyncTable Stats -- dict form, NO default literal
```
#### `SyncTable<...>` property — no default literal
Declare `SyncTable` (array form) or `SyncTable` (dict form) **without** an `= ...` initializer. The engine reserves the `=` slot of a SyncTable property for its own type bookkeeping and auto-initializes the property to an **empty collection** at runtime. Any literal you write (`= {}`, `= { key = val }`, `= nil`) is silently dropped — it is misleading noise, not a real default, and a round-trip through the codeblock will erase it.
Populate initial entries in `OnInitialize` / `OnBeginPlay`:
```lua
@Sync property SyncTable Stats -- empty at construction
@Sync property SyncTable Scores -- empty at construction
method void OnBeginPlay()
if self:IsServer() then
self.Stats["hp"] = 100
self.Stats["mp"] = 50
self.Scores:Add(0)
end
end
```
Assigning a plain Lua table to a `SyncTable` property at runtime is also rejected — the property accepts only its own proxy. Mutate it field by field (`self.Stats[k] = v`) or call its methods (`self.Scores:Add(v)` / `:Remove(v)` / `:Clear()`).
#### `SyncList` is not a user property type
`SyncList` is exposed only as a **readonly property on native engine Components** (e.g. `TagComponent.Tags`, `PhysicsColliderComponent.PolygonPoints`, `SkeletonRendererComponent.AnimationNames`, the various `JointComponent.Joints`). User scripts can **read** these and call their methods (`:Add(v)`, `:Remove(v)`, `:Clear()`, `.Count`, `:ToTable()`), but cannot declare `property SyncList<...> X` on their own `@Component` / `@Logic` and cannot instantiate `SyncList(...)`.
For synced collections in your own scripts, use `SyncTable` (array form) or `SyncTable` (dict form) — see above.
### Temporary properties (`_T`)
`self._T.` is non-synced, declaration-free ad-hoc state. Server and client keep their own values; never shown in inspector. Cannot be `@Sync`'d.
> ⚠️ **`_T` is the ONLY declaration-free field.** Assigning to any other undeclared `self.` is a runtime error — `cannot set , no such field` — that kills the calling method (usually all of `OnBeginPlay`). Every `self.` you set must be a declared `property`, or go through `self._T.`. The build log stays clean except an easily-missed `LIA-1114` Info (see §17.2).
### `OnSyncProperty` callback
Client-side hook fired when a `@Sync` property finishes synchronizing. **Must be `ClientOnly`** (cannot be changed). Available on Component and Logic. Not called for properties whose sync setting is None.
```lua
@ExecSpace("ClientOnly")
method void OnSyncProperty(string name, any value)
if name == "CurrentHp" then self:UpdateHpBar(value) end
end
```
### Property editor attributes
```lua
@DisplayName("...") @Description("...") @MaxLength(20) @HideFromInspector
@MinValue(0) @MaxValue(999) @Delta(5) -- Delta = mobile +/- step
```
---
## 8. Event System / RPC
### Static subscription — `@EventSender` + `handler`
```lua
@EventSender("Self") handler HandleHitEvent(HitEvent event) ... end
@EventSender("Service", "InputService") handler HandleKeyDown(KeyDownEvent event) ... end
```
`@EventSender` 1st arg: `"Self"` / `"LocalPlayer"` (no 2nd arg) · `"Entity"`,id / `"Model"`,id / `"Service"`,typeName / `"Logic"`,typeName.
### Dynamic subscription — `ConnectEvent` / `DisconnectEvent`
```lua
property any clickHandler = nil
self.clickHandler = entity:ConnectEvent(ButtonClickEvent, self.OnClick) -- OnBeginPlay
entity:DisconnectEvent(ButtonClickEvent, self.clickHandler) -- OnEndPlay (mandatory)
```
For per-element captured state (card IDs, slot indexes), use a closure handler; store the returned `EventHandlerBase` in a table and disconnect each in `OnEndPlay`.
```lua
property table clickHandlers = {}
for _, id in ipairs(cardIds) do
local capturedId = id
local h = e:ConnectEvent(ButtonClickEvent, function() self:OnCardClicked(capturedId) end)
table.insert(self.clickHandlers, { entity = e, handler = h })
end
```
> ⚠️ **`ConnectEvent` is on Entity / Logic / Service — NOT Component.** Components only *emit* events; subscribe on the owning **Entity** (or `_InputService` / `_`). `self.Entity.ButtonComponent:ConnectEvent(...)` runtime nils.
>
> ```lua
> property any clickHandler = nil
> property any keyHandler = nil
> self.clickHandler = self.Entity:ConnectEvent(ButtonClickEvent, self.OnClick)
> self.keyHandler = _InputService:ConnectEvent(KeyDownEvent, self.OnKeyDown)
> ```
> ⚠️ **`handler` vs `method void`** — `handler Name(Ev e)` pairs with `@EventSender(...)` and is wired by declaration. `method void Name(Ev e)` is the dynamic callback wired via `ConnectEvent(EvType, self.Name)`. Mixing them compiles but never fires (E-V1-5). If `@EventSender` is present → `handler`; if you'll call `ConnectEvent` → `method void`.
### CustomEvent — typed class style
The **only** way to author one is `@Event` + `extends EventType` with `property` fields. There is no inline factory.
```lua
@Event
script DamageDealtEvent extends EventType
property number amount = 0
end
local dmg = DamageDealtEvent(); dmg.amount = 50
self.Entity:SendEvent(dmg) -- via Entity / Logic / Service
self.Entity:ConnectEvent(DamageDealtEvent, self.OnDamage) -- first arg = event Type
method void OnDamage(DamageDealtEvent event) log(event.amount) end
```
NativeEvent (engine-provided, e.g., `HitEvent.TotalDamage/.AttackerEntity`, `ButtonClickEvent`, `StateChangedEvent.PrevState/.CurState`) — see `Environment/NativeScripts/Event/`.
---
## 9. Validity Checks and Method Override
### Validity checks
Accessing a deleted entity is a runtime error — always `isvalid()` first.
```lua
if isvalid(entity) then ... end
if isvalid(self.Entity.SomeComponent) then ... end
```
### Method override
In an `extends`-ing script, a `method` with the same signature as the parent overrides it. Built-in engine methods marked `---@sealed` cannot be overridden. Call the parent original via `__base:MethodName(args)`.
#### ⚠️ LEA-3014 `SignatureMismatch` — ExecSpace must match the parent
"Same signature" **includes `@ExecSpace`**. The override must be **byte-identical** to the parent's annotation block — including the **absence** of one. Adding `@ExecSpace("ServerOnly")` to "make it server-side" when the parent has none → runtime LEA-3014.
**Common offenders**: AttackComponent / HitComponent damage hooks (`CalcDamage`, `CalcCritical`, `GetCriticalDamageRate`, `GetDisplayHitCount`, `IsAttackTarget`, `IsHitTarget`, `OnAttack`) are all declared **without** `@ExecSpace`. Override with no annotation — they're still safe because the server-side hit pipeline is the only caller.
**Workflow**: read the parent in `.d.mlua` (§1.3) and copy its annotation block verbatim. Fix LEA-3014 by aligning the child's `@ExecSpace` to the parent's, never the reverse.
---
## 10. Input / Click Events — World vs UI (Do Not Confuse)
### World touch — two approaches
| Approach | Event | Connect on | Use |
|------|------|----------|-----|
| **Entity touch** — `TouchReceiveComponent` on entity | `TouchEvent` (+Hold/Release) | `entity:ConnectEvent(...)` | "Which entity was touched" — NPCs, items |
| **Screen touch** — no component | `ScreenTouchEvent` | `_InputService:ConnectEvent(...)` | "Where on the screen" — placement, move target |
Both events carry `TouchId` (int32) + `TouchPoint` (Vector2 screen coord). For world coords, `_UILogic:ScreenToWorldPosition(event.TouchPoint)`. Filter UI clicks with `_InputService:IsPointerOverUI()`. If `TouchEvent` misses, `ScreenTouchEvent` + `ScreenToWorldPosition` is the no-config fallback.
> ⚠️ **Physics colliders do NOT emit `TouchEvent`** — `BoxCollider2D`, `CircleCollider2D`, Rigidbody/Kinematicbody, and `TriggerComponent` all do not deliver touch input. Only **`TouchReceiveComponent`** emits `TouchEvent`/`TouchHoldEvent`/`TouchReleaseEvent`.
>
> **Setup**: `AutoFitToSize = true` (auto-fits TouchArea to the Sprite/Avatar scale) is the simplest path. Manual `TouchArea` should leave 10–20% slack beyond the sprite. `RelayEventToBehind = true` (default) forwards through; set `false` only to block.
>
> **Not firing? Check, in order**: (1) `TouchReceiveComponent` actually attached (in `.map` / `.model`); (2) `TouchArea` non-zero and entity visible on screen; (3) no front entity blocking with `RelayEventToBehind = false`; (4) handler stored in a `property any` (otherwise GC'd).
> **Selection rule**: "Which entity was touched" → `TouchEvent`; "Where on the screen" → `ScreenTouchEvent`.
### PC mouse buttons (left/right/middle) — use `KeyDownEvent`, not `ScreenTouchEvent.TouchId == 2`
`ScreenTouchEvent` fires on PC only for the left button (`TouchId == 1`); `TouchId == 2` is mobile two-finger touch — reading right-click through it works in the Maker simulator but is **silent no-input on real PCs**. For PC mouse buttons, `_InputService:ConnectEvent(KeyDownEvent, ...)` and branch on `event.key == KeyboardKey.Mouse0` / `Mouse1` / `Mouse2` (Left = 323, Right = 324, Middle = 325). To support both mobile multi-touch and PC, connect both `ScreenTouchEvent` and `KeyDownEvent` — they don't double-fire (no mobile right-click; no PC `TouchId == 2`).
### UI clicks
For UI entities (`./ui/*.ui`, `ui` tree), use **`ButtonComponent` + `ButtonClickEvent`**. Putting UI events on a world object (or vice versa) silently does nothing — decide first whether the target is a world object or a UI panel button.
---
## 11. Map Context and Entity Spawning
> **§1.7 trigger** — `Read` [builder-protocol.md](../msw-general/references/builder-protocol.md) + the matching per-builder protocol file before any spawn / `.map` / `.model` work.
### Children traversal
For "all X in the map" / "child named Y" queries, use `Entity`'s lookup toolkit:
| Member | Returns | Use |
|---|---|---|
| `Entity.Children` | `ReadOnlyList` (call `:ToTable()` to iterate) | Immediate children |
| `Entity:GetChildByName(name, recursive=false)` | `Entity` | By name |
| `Entity:GetChild(id, recursive=false)` | `Entity` | By UUID |
| `Entity:GetChildComponentsByTypeName(typename, recursive=false)` | `table` | All matching descendants |
| `Entity:GetFirstChildComponentByTypeName(typename, recursive=false)` | `Component` | First match |
```lua
local map = self.Entity.CurrentMap -- prefer this over service lookup
local units = map:GetChildComponentsByTypeName("script.MyUnit", false)
for _, child in ipairs(self.Entity.Children:ToTable()) do log(child.Name) end
```
The collection is `Children` — `ChildList`/`Childs`/`GetChildren()` are wrong (compile, runtime nil, `LIA-1114` Info). Runtime-spawned entities must be parented under `CurrentMap` to be findable.
### Native vs user component access
| Access | Works on |
|---|---|
| `entity.SomeComponent` (dot) | **Engine-native only** (`TransformComponent`, `ButtonComponent`, …) |
| `entity:GetComponent("script.MyUnit")` | User `@Component` (any) |
| `entity:GetFirstChildComponentByTypeName("script.MyUnit", true)` | User `@Component` on descendant |
User `@Component` typename is **always `"script."`** — `MyUnit.mlua` → `"script.MyUnit"`, regardless of feature-folder nesting. `entity.MyUnit` (dot) returns `nil` with `LIA-1114`. To pass user-component refs between scripts, declare a typed property (`property MyUnit unit = ""`) and inject UUID.
> ⚠ The method is `GetComponent` (overloaded as `GetComponent(Type)` and `GetComponent(string typename)` — see `Environment/NativeScripts/Misc/Entity.d.mlua`). The `*ByTypeName` suffix exists only on the **child** variants (`GetChildComponentsByTypeName` / `GetFirstChildComponentByTypeName`).
`GetComponent(string)` returns the abstract `Component` type, so member access on the result drops to dynamic dispatch and the LSP raises `LIA-1114` Info (or a `type mismatch` Error when the value is passed to a function whose signature expects the concrete user `@Component`). Cast with `---@type` to restore static typing:
```lua
---@type MyUnit
local unit = self.Entity:GetComponent("script.MyUnit")
unit:DoSomething() -- LSP now type-checks against MyUnit
```
### Spawning at runtime
- Use `_SpawnService:SpawnByModelId(id, name, pos, parent)` — **`parent` is required** (no default). Pass `self.Entity.CurrentMap`. `SpawnByEntity` differs — `parent = nil` is allowed.
- A `.model` template must already exist. New-object flow: **author `.model` → spawn or place on map**.
### Body components vs direct Position writes
Entities with a Body (Kinematic/Rigid/Sideview) ignore direct `TransformComponent.WorldPosition` writes — physics overwrites them next frame. Use instead:
- Per-frame: `MovementComponent:MoveToDirection(dir, dt)`
- Teleport (local): `MovementComponent:SetPosition(pos)` or `body:SetPosition(Vector2)`
- Teleport (world): `body:SetWorldPosition(Vector2)` — the standard absolute-place call for Kinematicbody on RectTile maps
- Direct Transform writes are OK only for Body-less entities (decorations, effects).
**Do NOT remove the Body as a workaround** — disables tile collision and enter/leave events (`NativeIssue_MissingComponent`).
---
## 12. Frequently Used Services / Logic
All services and logic are accessed via `_Name` (underscore + type name). Only the most common ones are listed.
| Service / Logic | Purpose |
|-------------|------|
| `_SpawnService` | Spawn entities (`SpawnByModelId`, `SpawnByEntity`). **There is no `Despawn` method** — remove spawned entities via `Entity:Destroy()` / `Entity:Destroy(delaySeconds)` (both `ControlOnly`). |
| `_TimerService` | Timers (`SetTimer`, `SetTimerRepeat`, `ClearTimer`) |
| `_EntityService` | Entity lookup (`GetEntity`, `GetEntities`, `GetEntitiesByPath`) |
| `_UserService` | Player lookup (`GetUsersByMapComponent(map.MapComponent)` returns all players currently on the given map — canonical "find players on this map" call, used by `Soldier`'s `FindNearestPlayer`). Returns `nil` when no users. |
| `_InputService` | Input state queries; receives `ScreenTouchEvent` |
| `_ResourceService` | Look up resource RUIDs; `LoadAnimationClipAndWait(ruid)` synchronously loads an AnimationClip (block for one frame — cache the result; wrap in `_ResourceService:PreloadAsync({ruid}, function() ... end)` if you want to avoid the block) |
| `_DataStorageService` | Persistent data (player saves) — **⚠️ Credit-billed. Do not call in `OnUpdate` / short timers; use `Batch*` in loops. Details: [references/datastorage.md](references/datastorage.md)** |
| `_UtilLogic` | Random, time, string, and math utilities |
| `_TweenLogic` | Tween animations (MoveTo, ScaleTo, RotateTo) |
| `_UILogic` | UI coordinate conversions (e.g., ScreenToWorldPosition) — ClientOnly |
> For the full list, read the `.d.mlua` files directly: `./Environment/NativeScripts/Service/` (46 files) and `./Environment/NativeScripts/Logic/` (9 files). For domain details, search via `msw-search`.
### Built-in globals accessed WITHOUT the `_` prefix
The `_Name` rule above applies to **Services and Logic only**. A few built-ins are exposed as plain globals — accessing them with a leading underscore is a runtime error (`nil` reference).
| Global (correct) | Wrong | Purpose |
|---|---|---|
| `Environment` | ❌ `_Environment` | Execution-environment queries — `Environment:IsMakerPlay()` / `IsMakerEdit()` / `IsPlay()` / `IsPublishedPlay()` / `IsMobilePlatform()` / `IsPCPlatform()`, `WorldId` property. `GetApplicationVersion()` is ClientOnly (nil on server). |
| `CollisionGroups` | ❌ `_CollisionGroups` | Table of `CollisionGroup` objects keyed by group name — `CollisionGroups.HitBox`, `.Monster`, `.Player`, etc. Built-ins: `Default` / `TriggerBox` / `HitBox` / `Interaction` / `Portal` / `Climbable`, plus any project-defined groups. Each entry has a `.Id` (string) and `:GetCollideGroups()`. |
---
## 13. Math, Utilities, Reserved Words, Type Annotations
### Math / utility examples
```lua
_UtilLogic:RandomDouble() -- 0.0~1.0
_UtilLogic:RandomIntegerRange(1, 10) -- inclusive
-- ElapsedSeconds / ServerElapsedSeconds: world-instance lifetime, NOT reset on OnBeginPlay.
-- They keep ticking across repeated play sessions in the Maker editor.
-- For per-session countdowns, see "Per-session timers" below.
_UtilLogic.ElapsedSeconds
_UtilLogic.ServerElapsedSeconds
```
### mlua utility classes
Collections beyond Lua stdlib: `List` / `ReadOnlyList` / `SyncList`, `Dictionary` / `ReadOnlyDictionary` / `SyncDictionary` (Sync* variants auto-sync server↔client). Other utility types: `DateTime`, `TimeSpan`, `Regex`, `Translator`, `Quaternion`, `Vector2Int`, `FastVector2/3` / `FastColor` (in-place ops for perf), `Item` (inventory).
> `.Values` / `.Keys` on `Dictionary` / `ReadOnlyDictionary` / `SyncDictionary` returns a plain Lua `table` — iterate with `ipairs` directly. No `:GetValues()` / `:ToTable()` / `pairs(dict)` wrapper needed. Lists are similar but require `:ToTable()` first (`ReadOnlyList` is not a Lua table).
>
> ```lua
> -- All connected players (server-side fan-out)
> for _, user in ipairs(_UserService.UserEntities.Values) do
> if isvalid(user) then ... end
> end
> ```
> Detailed APIs in `Environment/NativeScripts/` or via `msw-search`.
### Per-session timers — never anchor on `ElapsedSeconds`
Trap: `self.deadline = _UtilLogic.ElapsedSeconds + 15` in `OnBeginPlay`. The world instance survives multiple Maker play sessions, so the saved deadline is in the past on the next play and fires immediately.
For per-session countdowns, decrement a `delta`-driven property in `OnUpdate`:
```lua
property number waveCountdown = 0
method void OnBeginPlay() self.waveCountdown = 15 end
method void OnUpdate(number delta)
if self.waveCountdown > 0 then
self.waveCountdown = self.waveCountdown - delta
if self.waveCountdown <= 0 then self:StartWave() end
end
end
```
For session-relative elapsed time, baseline in `OnBeginPlay` (`self.startTime = _UtilLogic.ElapsedSeconds`) and subtract. Never compare raw `ElapsedSeconds` across sessions.
### Type annotations (code hints)
`---@type T` / `---@param` / `---@return` give editor autocomplete only — **no runtime effect**.
### Reserved words
Forbidden as identifiers: `handler`, `property`, `method`, `script`, `end`, `extends`, `self`, `nil`, `true`, `false`.
Applies to locals, parameters, properties, methods, dot-field names (`rec.handler`), and **bare** table keys (`{ handler = ... }`). Bracket-quoting an external string key (`rec["handler"]`) is fine, but prefer renaming internal keys (e.g., `eventHandler`).
---
## 14. External Tooling
- Maker MCP (`refresh`/`logs`/`play`/`stop`/`screenshot`/…): **`msw-general`** skill.
- API descriptions/examples/guides not in `.d.mlua`: **`msw-search`** skill.
- MCP wiring / `.mcp.json` / API key setup: share https://maplestoryworlds-creators.nexon.com/ko/docs?postId=1368
Debug order: **build logs → play → logs → stop → fix → diagnose → refresh → repeat**.
---
## 15. Script Authoring Workflow
1. **Search** existing scripts (§1.1) — modify if a similar one exists.
2. **Verify spec** (§1.3) — `.d.mlua` first, `msw-search` if insufficient.
3. **Decide path** (§1.2) — feature-folder mandatory; never write to `MyDesk/` root.
4. **Write**.
