Msw Scripting

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/<FeatureFolder>/<ScriptName>.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/:

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:

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 (core) plus the per-builder file for each type touched (builder-protocol-map.md / builder-protocol-model.md / 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.

-- ✅ 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

3. Script Types and Declarations

3.1 Component scripts (@Component)

Scripts attached to an Entity. Use self.Entity to access the owning entity.

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

@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 _<ExactScriptName> — 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.

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

@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:

5. Lifecycle

OnInitialize → OnBeginPlay → OnUpdate(delta) → OnEndPlay → OnDestroy
                                ↑
                  OnMapEnter / OnMapLeave (Component only, per transition)

Required pattern: everything connected in OnBeginPlay must be released in OnEndPlay (events, timers).

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

6. Execution Space (ExecSpace)

MSW is a server-client architecture. Every method must declare where it runs.

ExecSpace constraints on lifecycle methods

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.

@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>' name is unavailable.:

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.

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<k,v> 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.

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

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.

@Sync property number CurrentHp = 100
@TargetUserSync property number PrivateScore = 0
@Sync property SyncTable<number> Scores              -- array form, NO default literal
@Sync property SyncTable<string, number> Stats       -- dict form, NO default literal

SyncTable<...> property — no default literal

Declare SyncTable<V> (array form) or SyncTable<K, V> (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:

@Sync property SyncTable<string, number> Stats       -- empty at construction
@Sync property SyncTable<number> 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<V> is not a user property type

SyncList<V> 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<V> (array form) or SyncTable<K, V> (dict form) — see above.

Temporary properties (_T)

self._T.<name> 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.<name> is a runtime error — cannot set <name>, no such field — that kills the calling method (usually all of OnBeginPlay). Every self.<name> you set must be a declared property, or go through self._T.<name>. 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 changes. Must be ClientOnly (cannot be changed). Available on Component and Logic.

@ExecSpace("ClientOnly")
method void OnSyncProperty(string name, any value)
    if name == "CurrentHp" then self:UpdateHpBar(value) end
end

Property editor attributes

@DisplayName("...") @Description("...") @MaxLength(20) @HideFromInspector
@MinValue(0) @MaxValue(999) @Delta(5)   -- Delta = mobile +/- step

8. Event System / RPC

Static subscription — @EventSender + handler

@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

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.

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 / _<LogicName>). self.Entity.ButtonComponent:ConnectEvent(...) runtime nils.

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.

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

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

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 + 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:

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

User @Component typename is always "script.<FileBaseName>" — 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:

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

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

13. Math, Utilities, Reserved Words, Type Annotations

Math / utility examples

_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<T> is not a Lua table).

-- 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:

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.
5. Validate — mlua-diagnose hook auto-runs; fix until zero errors (§1.4).
6. Refresh — Maker MCP refresh (§1.5).
7. (If needed) play → logs → stop (§17).

Delete/rename also requires refresh + cleanup of references in .model / .map.

16. Attaching Scripts (Components) to Entities

§1.7 trigger — Read builder-protocol.md + the matching per-builder protocol file first. Never edit Components arrays as raw JSON.

• Attach to .model (preferred): ModelBuilder.addComponent() / upsertComponent(). Map instances inherit.
• Attach to one map instance only: MapBuilder.upsertComponent(name, "script.XXX", body).
• Global models (./Global/*.model): existing global templates affect the entire project and are edited in place via ModelBuilder + Maker Refresh. Do not create new files under Global/; create new custom models under RootDesk/MyDesk/Models/.

17. Playtesting and Debugging

The procedure for verifying behavior in play mode in Maker, then narrowing down bugs with runtime logs, screenshots, and simulated input.

For the MCP tool list, play-mode constraints, and refresh rules, see msw-general.

17.1 Always Check Build Logs First

Before every play, run logs(kind="build"). Build errors make scripts fail to load entirely (the component/logic behaves as if missing), and they often don't appear in runtime logs — most "code looks correct but doesn't work" reports trace to a missed build error. Fix → refresh → recheck until errors are zero, then play.

⚠️ Empty build logs ≠ build OK. Refresh-stage mlua conversion errors (Maker popup "An error occurred during mlua conversion") bypass the Build Console entirely: refresh still reports ok, logs(kind="build") stays at 0, and the error text lands only in logs(kind="normal"). If build logs are empty but a script still fails to load — or that popup is reported — read logs(kind="normal") next instead of looping refresh→build-check. Do not clear_logs until the cause is captured: clearing wipes the normal-log bucket, i.e. the only copy of the conversion error.

17.2 Error Classification

…(truncated)