msw-defaultplayer

MSW DefaultPlayer

Use the msw-general ModelBuilder to inspect/patch the DefaultPlayer model file, manage components, and configure movement / physics / HP / camera.

For costume / avatar equipment, see the msw-avatar skill. Costumes apply not only to DefaultPlayer but to any entity, so they live in a separate skill.

---

DefaultPlayer overview

What is DefaultPlayer?

The player character model provided by default in the MapleStory Worlds Maker workspace.

• When any user enters a world, a player entity is created based on this model.
• The model ID to use is specified by the PlayerUri property of DefaultUserEnterLeaveLogic.

File location and structure

DefaultPlayer is made up of two .model files:

Important: both files are located in ./Global/. Custom script files are created under ./RootDesk/MyDesk/.

DefaultPlayer is patched through ModelBuilder

DefaultPlayer is managed through the sibling msw-general/scripts/model/msw_model_builder.cjs, not raw JSON edits.

• Change a property value: ModelBuilder.read("./Global/DefaultPlayer.model").value(...)
• Add/remove a component: component() / removeComponent()
• Check the base component list: ModelBuilder.snapshot("./Global/Player.model")

---

File structure detail

Player.model (base)

Path: ./Global/Player.model
EntryKey: model://player

• Components: the full list of default components on the player (MOD.Core.* native components)
• Properties: model property → component property link definitions (properties editable from the inspector)
• Values: empty (defaults are provided by the engine)

DefaultPlayer.model (override)

Path: ./Global/DefaultPlayer.model
EntryKey: model://defaultplayer
BaseModelId: "player"

• Components: only the components added on DefaultPlayer (e.g. script.PlayerHit, script.PlayerAttack)
• Values: the array of overridden setting values

---

DefaultPlayer default component list

Native components inherited from Player.model:

Script components added in DefaultPlayer.model:

---

Quick reference — key components

---

DefaultPlayer Values structure

Format of each entry in the Values array of DefaultPlayer.model:

{
  "TargetType": "<component name> or null",
  "Name": "<property name>",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "<type info>"
  },
  "Value": <value>
}

TargetType rules

• null: a model property defined in Player.model's Properties (linked through Properties to the actual component property)
• "MOD.Core.<ComponentName>": directly override a property on a specific native component
• "script.<ScriptName>": a property of a custom script component

Model properties (TargetType: null)

Mapped to actual component properties through the links defined in Player.model's Properties.

Direct component override (TargetType: specific component)

Values that directly override a component property rather than going through a model-property link:

---

Movement components per map mode

See msw-general/references/platform.md §4 for the TileMapMode↔Body mapping table. Depending on the map mode, one of RigidbodyComponent / KinematicbodyComponent / SideviewbodyComponent is active.

---

Identifying a player (for script reference)

• entity.PlayerComponent ~= nil → whether the entity is a player
• _UserService.LocalPlayer → my player entity (client-only)
• _UserService:GetUserEntityByUserId(userId) → player entity for a specific user

---

Player entity runtime structure (root vs children)

A spawned player is not a single flat entity. At runtime the engine builds a small hierarchy under the player root, and avatar action selectors live on grandchild entities — not on the root. This affects how you look up components and how you trigger avatar poses.

Component → entity mapping

player:GetComponent("AvatarBodyActionSelectorComponent") returns nil and the LSP does not warn (the signature is Component, not nilable). The failure is only visible at runtime.

How to reach the selectors

-- ClientOnly context (recommended — the direct API)
local body  = self.Entity.AvatarRendererComponent:GetBodyEntity()
local face  = self.Entity.AvatarRendererComponent:GetFaceEntity()
local bodySelector = body and body:GetComponent("AvatarBodyActionSelectorComponent")
local faceSelector = face and face:GetComponent("AvatarFaceActionSelectorComponent")

-- Server or "either side" context (GetBodyEntity / GetFaceEntity are ClientOnly)
local bodySelector = self.Entity:GetFirstChildComponentByTypeName(
    "AvatarBodyActionSelectorComponent", true)

AvatarRendererComponent:GetBodyEntity() and GetFaceEntity() are declared @ExecSpace("ClientOnly") — calling them from a server-side method returns nil. Use GetFirstChildComponentByTypeName(name, recursive=true) as the cross-side fallback.

---

Triggering avatar poses — use StateComponent, never write the selector directly

A live player has a state machine running every tick: PlayerControllerComponent evaluates input/movement → StateComponent transitions (IDLE / MOVE / etc.) → AvatarStateAnimationComponent.ReceiveStateChangeEvent translates that into BodyActionStateChangeEvent → the selector's ActionState is rewritten.

This means writing AvatarBodyActionSelectorComponent.ActionState directly is a silent overwrite: the value applies for one frame, then the next state-machine tick maps the current StateComponent state back onto the selector and your write is gone. Logs print ActionState=Attack immediately after the assignment, but in play mode the pose flickers for one frame and disappears.

Correct entry point

local state = self.Entity:GetComponent("StateComponent")
state:ChangeState("ATTACK")   -- ActionSheet keys are UPPERCASE

State keys come from the player's ActionSheet. The DefaultPlayer ships with 11 UPPERCASE keys, each mapped to a default animation:

The state machine auto-returns to IDLE once the action finishes — no manual restore timer needed.

Casing pitfall: the string key passed to ChangeState is UPPERCASE ("ATTACK"). The enum value written to selector.ActionState directly (NPC path — see below) is MapleAvatarBodyActionState.Attack — PascalCase, separate API surface, same underlying state. Wrong casing on the string side ("attack" / "Attack") misses the ActionSheet mapping silently — no warning.

When can you write the selector directly?

Only on entities without a running PlayerControllerComponent + StateComponent + AvatarStateAnimationComponent stack — e.g. NPCs / monsters that use the avatar renderer for visuals but have no input controller driving a state machine. On those, selector.ActionState = MapleAvatarBodyActionState.<Pose> sticks. On DefaultPlayer-shaped entities, route through StateComponent:ChangeState(...) instead.

Key services at a glance (for script reference)

---

How to modify DefaultPlayer

Changing property values (Values)

Load ./Global/DefaultPlayer.model with ModelBuilder.read(), then update values with value().

Example: set movement speed to 2.0

const { ModelBuilder } = require("../msw-general/scripts/model/msw_model_builder.cjs");

const b = ModelBuilder.read("./Global/DefaultPlayer.model");

b.value(null, "speed", 2.0, "float")
  .value("MovementComponent", "InputSpeed", 2.0, "float")
  .write("./Global/DefaultPlayer.model");

Note: both the model property (TargetType: null, Name: "speed") and the direct component override (TargetType: "MOD.Core.MovementComponent", Name: "InputSpeed") can exist. Set both consistently through value().

Example: jump force 1.5 + HP 2000

const b = ModelBuilder.read("./Global/DefaultPlayer.model");

b.value(null, "jumpForce", 1.5, "float")
  .value("MovementComponent", "JumpForce", 1.5, "float")
  .value(null, "maxHp", 2000, "int")
  .write("./Global/DefaultPlayer.model");

Adding a new Values entry

Use ModelBuilder.value(targetType, name, value, typeKey). The builder generates the ValueType descriptor; do not hand-write type strings.

Common typeKey values: bool, int, float, double, string, vector2, vector3, data_ref, collision_group.

Adding a component

Use component() on ./Global/DefaultPlayer.model.

Adding a custom script component:

const b = ModelBuilder.read("./Global/DefaultPlayer.model");

b.component("script.MyCustomComponent")
  .write("./Global/DefaultPlayer.model");

Custom scripts (.mlua) must be created under ./RootDesk/MyDesk/. Write the script first, Maker refresh, then add "script.<ScriptName>" with the builder.

Adding a native component (e.g. SpriteRendererComponent):

const b = ModelBuilder.read("./Global/DefaultPlayer.model");

b.component("SpriteRendererComponent")
  .write("./Global/DefaultPlayer.model");

Removing a component

Use removeComponent() on DefaultPlayer.model. Related Values entries are removed by the builder.

Caution: components inherited from Player.model (the base) are not in DefaultPlayer.model's Components. Removing base components requires patching Player.model through ModelBuilder, and is generally not recommended.

---

Pitfalls (Common Pitfalls)

Common pitfalls when adding to Components and changing Values in DefaultPlayer.model.

Component list pitfalls

Values change pitfall — only jumpForce / speed need extra care

Most Values entries are in the TargetType=null (alias) form and can be set through ModelBuilder.value(null, ...). Only the two fields below are exceptions — both an alias and a native entry (TargetType="MOD.Core.MovementComponent") exist at the same time:

On entity spawn, Values are applied in array order and both write to the same native field; the native entry appears later in the array, so the native value wins.

• Wrong: editing only the alias side (jumpForce / speed) → overwritten by the later native entry and ignored
• Right: edit both consistently to the same value, or edit only the native side (JumpForce / InputSpeed)

Other alias-only entries (walkAcceleration, gravity, camera-related except cameraDeadZone, nameTag, damageSkinId, damageDelayPerAttack, triggerBody*, maxHp, etc.) can be modified through the alias as-is.

---

Hiding DefaultPlayer

DefaultPlayer's components are inherited from the base model, so they cannot be deleted. Disabling them via Enable=false is the only option.

Component keep/disable classification

Builder edit — add Enable=false to Values

Set the component values through ModelBuilder.value(). For components that don't yet have an Enable entry, the builder adds one.

const { ModelBuilder } = require("../msw-general/scripts/model/msw_model_builder.cjs");

const b = ModelBuilder.read("./Global/DefaultPlayer.model");

b.enable("AvatarRendererComponent", false)
  .value("KinematicbodyComponent", "EnableShadow", false, "bool")
  .write("./Global/DefaultPlayer.model");

After saving, Maker Refresh is required.

---

DefaultPlayer component extension patterns

• Non-avatar player: disable AvatarRendererComponent → add SpriteRendererComponent → set SpriteRUID.
• Collision setup: tweak ColliderType and CollisionGroup in TriggerComponent's Values.
• SpawnLocation: place a Special → SpawnLocation in the map (.map) file (revive position).

---

Workflows

Modifying basic player properties (movement speed, jump force, HP, etc.)

1. Load ./Global/DefaultPlayer.model with ModelBuilder.read()
2. Update values with value(targetType, name, value, typeKey)
3. If both the model property (TargetType: null) and the direct component override exist, set both consistently
4. write("./Global/DefaultPlayer.model")

Adding a custom script to the player

1. Write a new .mlua script under ./RootDesk/MyDesk/ (see the msw-scripting skill)
2. Maker refresh so the script type is registered
3. Load ./Global/DefaultPlayer.model with ModelBuilder.read()
4. Add "script.<ScriptName>" with component()
5. If needed, add default property values for the script with value()
6. write("./Global/DefaultPlayer.model")
7. Request Maker Refresh

Changing camera settings

1. Load ./Global/DefaultPlayer.model with ModelBuilder.read()
2. Set cameraDeadZone, cameraSoftZone, cameraDamping, cameraScreen, cameraDutch, cameraOffset with value()
3. write("./Global/DefaultPlayer.model")

---

Boundaries and caveats

In scope

• Inspect/patch the DefaultPlayer/Player model files through ModelBuilder
• Add/remove components through component() / removeComponent()
• Movement / physics / HP / camera settings through value()

Out of scope

• Costume / avatar equipment → msw-avatar skill
• UI editor → .ui files under ./ui/ (dedicated skill)
• Map editing → .map files under ./map/ (dedicated skill, including NPC/monster spawn)
• General scripts / resources → each dedicated skill

Constraints

1. Careful with Global/: DefaultPlayer.model and Player.model live in ./Global/. This folder is reserved for engine default templates, so creating new files here is not recommended.
2. Custom script location: new script files must be created under ./RootDesk/MyDesk/.
3. Map mode caveat: the active movement component differs depending on the map mode (MapleTile/RectTile/SideViewRectTile).
4. ValueType correctness: when adding a Values entry, use ModelBuilder.value() with an explicit typeKey; do not hand-write ValueType.
5. Maker Refresh: after adding/modifying scripts, Maker Refresh is required (.codeblock is auto-generated).