msw-avatar

SKILL.md

MSW Avatar (Costume · Animation)

An avatar is managed along two axes.

Costume (appearance): MOD.Core.CostumeManagerComponent — which items are equipped (17 slots).

Animation (motion): AvatarStateAnimationComponent + AvatarRendererComponent — which state clip is played (14 default states + custom actions).

Edit workspace files directly, then call the refresh tool of msw-maker-mcp so the editor picks up the change.

This document covers costume (file-edit based) first, then animation (script based) at the end.

Workspace path rule: maps ./map/, UI ./ui/, scripts and other assets ./RootDesk/MyDesk/, global models such as DefaultPlayer/Player ./Global/.

Where to edit, by target

Target
File to edit
Notes

DefaultPlayer
./Global/DefaultPlayer.model
Override CostumeManagerComponent properties via the Values array

Player (base)
./Global/Player.model
Costume defaults are usually overridden in DefaultPlayer.model, not here

Entities placed in a map (NPC, monster, etc.)
./map/{mapName}.map
The CostumeManagerComponent block inside that entity's jsonString.@components

Entities that reference a custom model only
The corresponding .model (e.g. under ./RootDesk/MyDesk/)
When the map has no inline component and the entity is bound only by modelId, edit the model side

Read (equivalent to get): read the file above and inspect the CostumeManagerComponent-related fields / Values entries. If Maker MCP is connected, you can use get_component as a runtime/editor snapshot helper (see the msw-maker-mcp skill).

Apply (equivalent to set): write values into the file, then call refresh.

Applying changes: MCP refresh

After saving the file you must call the refresh tool of the msw-maker-mcp server to sync Maker and its visual state. (See the tool list in the msw-maker-mcp skill.)

RUID (resource unique ID)

The string written into a costume is an avatar item RUID (typically a 32-character hex string).

Never guess or fabricate an RUID. Look it up with the msw-search skill — for the avatar RUID workflow (default body/head, item detail, render composition) see ../msw-search/references/resource/avatar.md; for generic search see ../msw-search/references/resource/search.md; for single-item detail see ../msw-search/references/resource/detail.md.

The script API SetEquip(MapleAvatarItemCategory, itemRUID) and the value stored in the editor/model are the same RUID string.

Custom*Equip slots only accept a plain Guid. Any prefixed form — including thumbnail://<ruid> — is silently rejected and the slot is left unequipped (no error, no warning). RUIDs returned by msw-search are already plain Guids; do not prepend a scheme. See the msw-sprite-ruid skill for the broader thumbnail / icon rule.

CostumeManagerComponent overview

Attached to entities that use an avatar (player, NPC, etc.). Equipment slots are exposed as 17 string properties named Custom*Equip, and from scripts you access them via GetEquip / SetEquip with the MapleAvatarItemCategory enum.

Other synced properties

Property
Type
Description

UseCustomEquipOnly
boolean (default false)
When true, the user account's default costume is ignored and only costumes assigned via script/model are used. Important when you want to lock the appearance inside a world.

DefaultEquipUserId
string
Clones the equipment of the specified user, then applies custom equipment on top. Users who are not currently online can also be specified. If that user later changes equipment, the reflected appearance may change.

EquippedItems
read-only
Actual equipped info at runtime. Cannot be modified from script.

17 slots ↔ property ↔ MapleAvatarItemCategory

The 17 equipment string fields of CostumeManagerComponent map to the engine enum MapleAvatarItemCategory as follows. (Enum definition: see Environment/NativeScripts/Enum/MapleAvatarItemCategory.d.mlua.)

#
Component property (string RUID)
MapleAvatarItemCategory
Notes

1
CustomBodyEquip
Body (1)
Skin / body

2
CustomHairEquip
Hair (3)
Hair

3
CustomFaceEquip
Face (4)
Face / face shape

4
CustomCapEquip
Cap (5)
Hat

5
CustomCapeEquip
Cape (6)
Cape

6
CustomCoatEquip
Coat (7)
Coat (top)

7
CustomLongcoatEquip
Longcoat (9)
Longcoat — an item class that occupies both the top and bottom slots

8
CustomPantsEquip
Pants (10)
Bottom

9
CustomGloveEquip
Glove (8)
Gloves

10
CustomShoesEquip
Shoes (12)
Shoes

11
CustomOneHandedWeaponEquip
OneHandedWeapon (13)
One-handed weapon

12
CustomTwoHandedWeaponEquip
TwoHandedWeapon (14)
Two-handed weapon — occupies both the one-handed weapon slot and the sub-weapon slot

13
CustomSubWeaponEquip
SubWeapon (15)
Sub-weapon

14
CustomFaceAccessoryEquip
FaceAccessory (16)
Face accessory

15
CustomEyeAccessoryEquip
EyeAccessory (17)
Eye accessory

16
CustomEarAccessoryEquip
EarAccessory (18)
Ear accessory

17
CustomEarEquip
Ear (19)
Ear (body part)

Enum values without a direct 17-field counterpart

MapleAvatarItemCategory
Description

Head (2)
Close to "not used as equipment" — handled automatically to match the body color. There is no CustomHeadEquip field.

Invalid (0)
Used to detect error / undefined values.

Shield (11)
Per the enum comment, it uses the SubWeapon slot. In storage it is safest to treat it as mutually exclusive with CustomSubWeaponEquip.

Mutual exclusion / slot occupancy rules (must understand)

Longcoat ↔ Coat + Pants

Longcoat is designed to occupy both the Coat and Pants slots. When equipping a longcoat, put the longcoat RUID in CustomLongcoatEquip and resolve the combination with coat/pants logically — normally when a longcoat is in use, leave coat/pants empty or avoid conflicting visuals.

Two-handed weapon ↔ One-handed weapon + sub-weapon

TwoHandedWeapon uses both the one-handed weapon slot and the sub-weapon slot. When using a two-handed weapon, center on CustomTwoHandedWeaponEquip and make sure values are not also set for one-handed/sub-weapon — avoid double equipping.

Shield ↔ Sub-weapon

Shield uses the sub-weapon slot. Do not expect another sub-weapon to coexist with CustomSubWeaponEquip.

Empty string = unequip

Just like SetEquip(category, "") in script, leaving the field as "" in a file means the slot is unequipped.

DefaultPlayer.model — putting costume into Values

Add or modify an entry in the ContentProto.Json.Values array of ./Global/DefaultPlayer.model.

TargetType: "MOD.Core.CostumeManagerComponent"

Name: a property name from the table above (e.g. CustomCapEquip, UseCustomEquipOnly)

ValueType: follow the same pattern as other Values entries already in DefaultPlayer.model. Strings use System.String, mscorlib, ..., booleans use System.Boolean, mscorlib, ...

Value: the RUID string or true / false

If the same (TargetType, Name) already exists, update that entry only; otherwise append a new object to the array.

String slot example (structure only; replace the RUID via search)

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "CustomCapEquip",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": "PUT_32_HEX_RUID_HERE"
}

UseCustomEquipOnly example

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "UseCustomEquipOnly",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": true
}

Map entities — edit in the .map file

Open the entity record of the target map under ./map/.

Find the target entity (by name/path/id) in the ContentProto.Entities array.

In jsonString["@components"], find the object with "@type": "MOD.Core.CostumeManagerComponent".

Edit Custom*Equip, UseCustomEquipOnly, DefaultEquipUserId, etc. on that object directly.

Confirm that MOD.Core.CostumeManagerComponent is also listed in the componentNames string list, and that this list is consistent with the components array.

If the map uses binary-only format, the editing tool may differ depending on workspace policy. When the file opens as JSON text, follow the structure above.

Mapping GET /v3/avatars results to slots

Map the category field of an item returned by GET /v3/avatars to a Custom*Equip property. For the search method, see the msw-search skill → references/resource/avatar.md.

API category
Custom*Equip property
MapleAvatarItemCategory

body
CustomBodyEquip
Body (1)

hair
CustomHairEquip
Hair (3)

face
CustomFaceEquip
Face (4)

faceaccessory
CustomFaceAccessoryEquip
FaceAccessory (16)

eyeaccessory
CustomEyeAccessoryEquip
EyeAccessory (17)

earaccessory
CustomEarAccessoryEquip
EarAccessory (18)

cap
CustomCapEquip
Cap (5)

cape
CustomCapeEquip
Cape (6)

longcoat
CustomLongcoatEquip
Longcoat (9)

coat
CustomCoatEquip
Coat (7)

pants
CustomPantsEquip
Pants (10)

glove
CustomGloveEquip
Glove (8)

shoes
CustomShoesEquip
Shoes (12)

weapon
CustomOneHandedWeaponEquip
OneHandedWeapon (13)

twohandweapon
CustomTwoHandedWeaponEquip
TwoHandedWeapon (14)

subweapon
CustomSubWeaponEquip
SubWeapon (15)

shield
CustomSubWeaponEquip
Shield (11) — shares the SubWeapon slot

Avatar resource search reference

msw-search skill → references/resource/avatar.md: details on GET /v3/avatars (costume search), default body/head, GET /v3/avatars/{ruid}, render composition, etc.

Combine the category search and detail API to collect equipment RUIDs.

Avatar tint / alpha (visual recoloring)

For color and transparency effects (hit flash, ghost fade, palette swap, etc.) on any entity that has AvatarRendererComponent attached — DefaultPlayer, avatar-bearing NPCs, monsters — use the renderer's own methods. SpriteRendererComponent.Color and FlipX are a silent no-op on an avatar entity (the avatar renderer paints over the sprite renderer's output even though isvalid(spriteRenderer) returns true).

Method
Signature
Notes

SetColor
(r, g, b, a [, targetUserId])
r/g/b/a are floats in 0~1. Tints the whole avatar. Client ExecSpace.

SetAlpha
(a [, targetUserId])
Float in 0~1. Independent transparency. Client ExecSpace.

SetAvatarPartColor
(category, r, g, b, a [, targetUserId])
Tint only one MapleAvatarItemCategory slot.

@ExecSpace("Client")
method void FlashRed()
    local renderer = self.Entity.AvatarRendererComponent
    if isvalid(renderer) == false then return end
    renderer:SetColor(1.0, 0.25, 0.25, 1.0)   -- red flash
    wait(0.1)
    renderer:SetColor(1.0, 1.0, 1.0, 1.0)     -- restore
end

For avatar facing/flip, use the facing API on MovementComponent (e.g. MoveDirection) instead of writing the sprite-level flip — same silent-no-op reason.

Avatar animation — overall structure

Avatar animation flows through a 3-layer pipeline. Working on only one layer leads to the other layers overwriting your changes and producing unintended motions.

[1] Input / game logic
       │  PlayerControllerComponent · scripts
       ▼
[2] StateComponent       ──── StateChangeEvent ────▶ AvatarStateAnimationComponent
       (e.g. "ATTACK")          (CurrentStateName)        (StateToAvatarBodyActionSheet
                                                            or ActionSheet lookup)
                                                                 │
                                                                 ▼
[3] AvatarRendererComponent ◀── BodyActionStateChange / ActionStateChanged ── body entity
       (actual sprite playback)

Key distinctions:

Term
Format
Example

State key
UPPERCASE
IDLE, MOVE, ATTACK, HIT, CROUCH, FALL, JUMP, CLIMB, LADDER, DEAD, SIT, ATTACK_WAIT

AvatarBodyActionStateName (Value side)
lowercase
stand, walk, attack, hit, crouch, fall, rope, ladder, dead, sit, alert, fly, blink, heal

MapleAvatarBodyActionState (enum)
PascalCase
Stand, Walk, Attack, Hit, Crouch, Fall, Sit, Rope, Ladder, Dead, Blink, Fly, Heal, Alert, Invalid

CoreActionName / PartsActionName (actual sprite action ID)
lowercase + digits
stand1, walk1, swingO1, shoot1, prone, jump, alert, etc.

Common confusion: "attack" is not a State. The State is the uppercase ATTACK, the mapping Value is the lowercase attack (= MapleAvatarBodyActionState.Attack), and that Value is then resolved into a sprite action ID such as swingO1 / shoot1 depending on the weapon. From script, the call that triggers the state is StateComponent:ChangeState("ATTACK") (UPPERCASE string) — "Attack" or "attack" silently misses (no error, the state simply does not change).

AvatarStateAnimationComponent — state ↔ motion mapping

MOD.Core.AvatarStateAnimationComponent holds both systems.

Property
Used when
Type
Notes

IsLegacy
Switch between the two systems
boolean (default false)
true = use ActionSheet, false = use StateToAvatarBodyActionSheet

ActionSheet
IsLegacy = true (old)
SyncDictionary<string, string>
State→AnimationKey, e.g. "ATTACK" → "attack"

StateToAvatarBodyActionSheet
IsLegacy = false (new, default)
SyncDictionary<string, AvatarBodyActionElement>
e.g. "ATTACK" → {AvatarBodyActionStateName="attack", PlayRate=1.33}

StateToAvatarBodyActionSheet default mapping (the 11 default keys when IsLegacy=false)

Key (State)
AvatarBodyActionStateName
PlayRate
Trigger condition (when PlayerControllerComponent is present)

IDLE
stand
1.0
No input

MOVE
walk
1.68
Left/right movement

ATTACK
attack
1.33
Left Ctrl (Attack action)

HIT
hit
1.0
Hit processing by HitComponent

CROUCH
crouch
1.0
Down arrow

FALL
fall
1.0
Falling in the air

JUMP
fall
1.0
Space (Jump action)

CLIMB
rope
1.0
Entering a rope

LADDER
ladder
1.0
Entering a ladder

DEAD
dead
1.0
Death

SIT
sit
1.0
C (Sit action)

Note that State keys are uppercase while AvatarBodyActionStateName values are lowercase.

Default resolution table: MapleAvatarBodyActionState → actual action ID

An AvatarBodyActionStateName string ("attack", "stand", etc.) is cast to the enum MapleAvatarBodyActionState, and the engine then resolves it into the following defaults, synthesizing an ActionStateChangedEvent.

MapleAvatarBodyActionState
CoreActionName
PartsActionName
PlayRate
PlayType

Stand
stand1 / stand2
same
1
ZigzagLoop

Walk
walk1 / walk2
same
1
Loop

Attack
alert (default when no weapon)
alert
1
Loop

Crouch
prone
prone
1
Loop

Fall
jump
jump
1
Loop

Sit
sit
sit
1
Loop

Rope
rope
rope
1
Loop

Ladder
ladder
ladder
1
Loop

Dead
dead
stand1
1
Loop

Blink
blink
blink
1
Loop

Fly
fly
fly
1
Loop

Hit
alert
alert
1
ZigzagLoop

Alert
alert
alert
1
ZigzagLoop

Heal
heal
heal
1
Loop

When a weapon is equipped, Attack is automatically replaced with the sprite action ID matching the weapon type (see the next table). Holding a one-handed sword produces a sword swing; holding a bow produces a bow shot.

Per-weapon attack resolution — candidate sprite action IDs

When ATTACK is triggered, the engine looks at the equipped weapon (MapleAvatarItemCategory) and plays one of the following action IDs.

Weapon class
Candidate CoreActionName / PartsActionName

One-handed sword / dagger (OneHandedWeapon)
swingO1, swingO2, swingO3, stabO1, stabO2

Two-handed sword / hammer (TwoHandedWeapon)
swingT1, swingT2, swingT3, stabT1, stabT2

Bow (TwoHandedWeapon, bow family)
swingT1, swingT3, shoot1

Staff / wand
swingO1, swingO2, swingO3

No weapon (default body)
No dedicated attack clip → displayed via alert etc.

Even within the same class, the set of action IDs used may differ per item metadata. The table above lists the representative candidates used by the SDK guide (_ActionNameLogic).

PlayerControllerComponent and auto state addition

When MOD.Core.PlayerControllerComponent is attached to a player entity, the following States are added automatically to StateComponent and transition automatically on key input:

MOVE, CLIMB, LADDER, CROUCH, JUMP, FALL, ATTACK, ATTACK_WAIT, SIT

So when a DefaultPlayer presses Ctrl, the ATTACK state activates automatically and the mapped attack body motion (= the per-weapon sword/bow/staff swing) plays automatically — even with no extra scripting, the sword still swings.

Auto playback ↔ manual ActionStateChangedEvent collision (★ common pitfall)

Symptom: Even after sending a custom action like shoot1 via ActionStateChangedEvent from script, the sword swing (or the weapon's default attack) still plays, or your custom action shows for a single frame and is immediately overwritten.

Cause: While ATTACK is active, AvatarStateAnimationComponent continuously re-sends the mapped attack body motion. Your single-shot event is immediately overwritten.

Resolution strategies

Strategy
Method
When to use

A. Remove the mapping
Call asac:RemoveActionSheet("ATTACK") to drop the key. Then play the action directly via ActionStateChangedEvent.
When you want to fully replace the attack motion with a custom one (bow shot, spellcast, etc.)

B. Change the mapping
Call asac:SetActionSheet("ATTACK", "<Body Action name>") or change StateToAvatarBodyActionSheet["ATTACK"] to a different MapleAvatarBodyActionState.
When you want to switch to a different built-in state animation (e.g. ATTACK→heal)

C. Force reset
Send BodyActionStateChangeEvent with needResetAction=true.
When you want to restart the same state

D. Swap the weapon
Replace the weapon slot of CostumeManagerComponent with a bow RUID.
When you simply want to change the weapon variant of the attack motion (the most intuitive option)

Strategy A example — turn off sword swing, replace with bow shot

@Component
script PlayerAttack extends AttackComponent

	@HideFromInspector
	property any Shape = nil

	@ExecSpace("ServerOnly")
	method void OnBeginPlay()
		self.Shape = BoxShape(Vector2.zero, Vector2.one, 0)

		-- Remove the attack(=sword swing) mapping that the engine auto-plays during ATTACK
		local asac = self.Entity.AvatarStateAnimationComponent
		if isvalid(asac) then
			asac:RemoveActionSheet("ATTACK")
		end
	end

	@ExecSpace("ServerOnly")
	method void AttackNormal()
		-- ... damage resolution ...
		self:PlayShootAnimation()
	end

	@ExecSpace("Client")
	method void PlayShootAnimation()
		local body = self.Entity.AvatarRendererComponent:GetBodyEntity()
		if isvalid(body) == false then return end

		local event = ActionStateChangedEvent()
		event.CoreActionName = "shoot1"
		event.PartsActionName = "shoot1"
		event.PlayType = SpriteAnimClipPlayType.Onetime
		body:SendEvent(event)
	end

	@ExecSpace("ServerOnly")
	@EventSender("Self")
	handler HandlePlayerActionEvent(PlayerActionEvent event)
		if event.ActionName == "Attack" then
			self:AttackNormal()
		end
	end
end

RemoveActionSheet / SetActionSheet must be called on the server for the change to sync, because StateToAvatarBodyActionSheet is a @Sync property.

Strategy D example — equip a bow via CostumeManagerComponent

If you add a bow RUID to Values in ./Global/DefaultPlayer.model, the engine will automatically pick the shoot1 motion during ATTACK without changing the mapping.

{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "CustomTwoHandedWeaponEquip",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": "<bow RUID — obtain via msw-search>"
},
{
  "TargetType": "MOD.Core.CostumeManagerComponent",
  "Name": "UseCustomEquipOnly",
  "ValueType": {
    "$type": "MODNativeType",
    "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
  },
  "Value": true
}

14 states vs custom actions — which do you trigger yourself?

The 14 body motions already known to AvatarStateAnimationComponent / MapleAvatarBodyActionState and arbitrary sprite action IDs outside that set (e.g. swingO2, shoot1, dance, cast1) go through different paths.

The 14 body motions the engine handles automatically (= members of MapleAvatarBodyActionState)

These are the names usable as the Value of StateToAvatarBodyActionSheet/ActionSheet. Once you map a State to one of these, it plays automatically.

Body motion name
Enum
Meaning

stand
Stand
Idle

walk
Walk
Movement

attack
Attack
Attack (the sprite ID is auto-selected by weapon)

hit
Hit
Hit

crouch
Crouch
Crouch

fall
Fall
Fall

rope
Rope
Holding a rope

ladder
Ladder
Ladder

dead
Dead
Death

sit
Sit
Sit

heal
Heal
Heal

alert
Alert
Alert

fly
Fly
Fly

blink
Blink
Blink

Anything else — play directly via ActionStateChangedEvent

For arbitrary sprite action IDs outside the 14 enum members (e.g. shoot1, swingO2, cast1, throw1, dance, cheer), use the following procedure.

Playback pipeline

From the entity's AvatarRendererComponent, call GetBodyEntity() to obtain the body entity of the avatar. Animation events go to the body entity, not the avatar root.

Create an ActionStateChangedEvent and fill its fields.

Send it to the body entity via body:SendEvent(event).

Animation only needs to be seen by each client, so this is typically scoped to @ExecSpace("Client"). Game logic (damage, projectile spawn, etc.) belongs on the ServerOnly side.

Main fields of ActionStateChangedEvent (constructor: ActionStateChangedEvent(coreActionName, partsActionName, playRate=1, playType=Loop, startFrameIndex=0, endFrameIndex=2147483647))

Field
Type
Default
Description

CoreActionName
string
""
Animation ID to play on the core parts (body). Required (e.g. "shoot1", "swingO1")

PartsActionName
string
""
Animation ID to play on the sub-parts. Required — usually the same value as CoreActionName

PlayRate
float
1
Playback speed multiplier (1.0 = normal speed, 1.5 = 1.5×)

PlayType
SpriteAnimClipPlayType
Loop
Onetime / Loop / ZigzagLoop. For one-shot actions use Onetime

StartFrameIndex
int32
0
Start frame (negative values are clamped to 0)

EndFrameIndex
int32
2147483647
End frame (clamped if it exceeds the total frame count)

SpriteAnimClipPlayType:

Value
Meaning

Onetime
Plays once, then stops

Loop
0→end, repeated

ZigzagLoop
0→end→0, repeated

BodyActionStateChangeEvent — high-level event for the 14 built-in states

Directly specifies a MapleAvatarBodyActionState enum value. You don't have to memorize per-weapon action IDs, and you can force-restart the same state via needResetAction=true.

Unlike ActionStateChangedEvent, SendEvent targets the avatar root entity (self.Entity), not the body entity.

local event = BodyActionStateChangeEvent()
event.ActionState = MapleAvatarBodyActionState.Fly
event.needResetAction = true
event.startFrameIndex = 1
event.endFrameIndex = 2
self.Entity:SendEvent(event)
-- Internally converted to ActionStateChangedEvent("fly", "fly", 1, Loop, 1, 2) and dispatched

Field
Description

ActionState
MapleAvatarBodyActionState enum (Stand/Walk/Attack/Hit/...)

needResetAction
When true, force-restarts from the beginning even if the state is already playing

playRate / startFrameIndex / endFrameIndex
Same as ActionStateChangedEvent

Choosing between them

Arbitrary sprite action ID (shoot1, swingO2, dance, etc.) → ActionStateChangedEvent (send to body entity)

One of the 14 enum states (Stand/Walk/Attack/...) → BodyActionStateChangeEvent (send to root entity)

Example — playing the arrow-firing (shoot) animation

A typical pattern: on the server, the attack input spawns a projectile; on the client, the shoot1 action plays.

@Component
script PlayerAttack extends Component

    property string ArrowModelId = "model://bc9f9d0e-2b5d-4b3b-a115-d857f85e9145"

    @HideFromInspector
    property integer ArrowCount = 0

    @ExecSpace("ServerOnly")
    method void FireArrow()
        if self.ArrowModelId == nil or self.ArrowModelId == "" then
            log_warning("PlayerAttack: ArrowModelId is not set")
            return
        end

        local playerController = self.Entity.PlayerControllerComponent
        local transform = self.Entity.TransformComponent
        if isvalid(playerController) == false or isvalid(transform) == false then
            return
        end

        local dirX = playerController.LookDirectionX
        if dirX == 0 then dirX = 1 end

        local worldPos = transform.WorldPosition
        local spawnPos = Vector3(worldPos.x + 0.35 * dirX, worldPos.y + 0.35, worldPos.z)

        self.ArrowCount += 1
        local arrowName = "PlayerArrow_" .. tostring(self.ArrowCount)

        local parent = self.Entity.CurrentMap
        if isvalid(parent) == false then
            parent = self.Entity.Parent
        end

        local arrow = _SpawnService:SpawnByModelId(self.ArrowModelId, arrowName, spawnPos, parent)
        if isvalid(arrow) == false then
            log_warning("PlayerAttack: failed to spawn arrow")
            return
        end

        local arrowProj = arrow.ArrowProjectile
        if isvalid(arrowProj) then
            arrowProj:Fire(Vector2(dirX, 0))
        end

        self:PlayShootAnimation()
    end

    @ExecSpace("Client")
    method void PlayShootAnimation()
        local avatarRenderer = self.Entity.AvatarRendererComponent
        if isvalid(avatarRenderer) == false then
            return
        end
        local body = avatarRenderer:GetBodyEntity()
        if isvalid(body) == false then
            return
        end

        local event = ActionStateChangedEvent()
        event.CoreActionName = "shoot1"
        event.PartsActionName = "shoot1"
        event.PlayRate = 1.5
        event.PlayType = SpriteAnimClipPlayType.Onetime
        body:SendEvent(event)
    end

    @ExecSpace("ServerOnly")
    @EventSender("Self")
    handler HandlePlayerActionEvent(PlayerActionEvent event)
        local ActionName = event.ActionName

        if ActionName == "Attack" then
            self:FireArrow()
        end
    end

end

Decision flow

Is the motion you want to play one of the 14 built-in states (stand, walk, attack, hit, crouch, fall, rope, ladder, dead, sit, heal, alert, fly, blink)?

YES → Just assign the clip in the matching slot of AvatarStateAnimationComponent. No script needed.

NO → continue below.

For custom actions (e.g. shoot1, cast1, dance), create an ActionStateChangedEvent and SendEvent it to the body entity returned by AvatarRendererComponent:GetBodyEntity().

Split execution spaces: input handling and damage resolution on the server (ServerOnly), animation playback on the client (Client).

Common mistakes

Confusing the State key with AvatarBodyActionStateName (=the enum). State keys are uppercase (ATTACK); mapping Values are lowercase (attack). If you swap Key/Value in StateToAvatarBodyActionSheet, the mapping silently fails.

Sending only ActionStateChangedEvent without disabling auto playback. When Ctrl is pressed the ATTACK state activates automatically, and the mapped attack body motion immediately overwrites your event. To use a custom attack motion you must clean up the mapping with RemoveActionSheet("ATTACK") or SetActionSheet("ATTACK", "<desired motion>").

Wrong SendEvent target for ActionStateChangedEvent: it must be the body entity returned by AvatarRendererComponent:GetBodyEntity(). Sending it to self.Entity (the avatar root) or to a component does not play. (Conversely, BodyActionStateChangeEvent goes to the root entity.)

Writing AvatarBodyActionSelectorComponent.ActionState directly on a DefaultPlayer-shaped entity (running PlayerControllerComponent + StateComponent + AvatarStateAnimationComponent). The controller re-evaluates ground/move/input each tick and calls ChangeState on transitions; the resulting StateChangeEvent → BodyActionStateChangeEvent repaints the selector, silently dropping your write. Use StateComponent:ChangeState("UPPERCASE_KEY") instead. Direct selector writes only stick on NPCs/monsters without that controller stack.

Trying to put arbitrary state names into AvatarStateAnimationComponent. Values outside the 14 enum members (MapleAvatarBodyActionState) — e.g. shoot, cast, dance — are ignored. Custom IDs must go through ActionStateChangedEvent.

Forgetting PartsActionName. If you set only CoreActionName, the sub-parts (weapon, hat, cape, etc.) won't be resolved, so you can end up with the upper body moving while the weapon stays frozen. Use the same value as CoreActionName.

Leaving PlayType unset. The default is Loop, which causes one-shot actions to repeat forever. For one-shot actions, set SpriteAnimClipPlayType.Onetime explicitly.

Calling RemoveActionSheet/SetActionSheet on the client. StateToAvatarBodyActionSheet is a @Sync property — these must be called on the server to reach all clients.

Forgetting to separate server/client execution spaces. Game logic (damage, projectiles) = ServerOnly; animation playback = Client. Mixing them in one place leads to duplicated playback per client or missing visuals.

Expecting a bow motion without equipping a bow. Firing shoot1 puts the body in the bow pose, but if no bow RUID is set in CustomTwoHandedWeaponEquip, no bow is drawn in the hand. For a natural visual, set the motion and the weapon together.

Related skills

Skill
Purpose

msw-defaultplayer
Structure of ./Global/DefaultPlayer.model / Player.model and Values rules

msw-search
RUID lookup, references/resource/avatar.md

msw-maker-mcp
refresh, optionally get_component / set_property (when combined with runtime tweaks)

Summary checklist

Costume

Obtain the RUID via the resource search / avatar reference docs.

DefaultPlayer / Player → Values in ./Global/*.model (or the base model definition).

Map entities → @components of the target entity inside ./map/*.map.

Respect the Longcoat / two-handed weapon / shield ↔ sub-weapon exclusion rules.

Decide whether to ignore the user's account default costume via UseCustomEquipOnly.

After saving, call msw-maker-mcp → refresh.

Animation

Distinguish State keys (uppercase) from body motion names (lowercase). Form: StateToAvatarBodyActionSheet["ATTACK"] = AvatarBodyActionElement("attack", 1.33).

If the desired motion is among the 14 enum body motions (stand·walk·attack·hit·crouch·fall·rope·ladder·dead·sit·heal·alert·fly·blink), just define the mapping — done.

For other action IDs (shoot1, swingT3, dance, etc.), create an ActionStateChangedEvent and SendEvent it to the result of AvatarRendererComponent:GetBodyEntity(). To restart a state inside the enum, use BodyActionStateChangeEvent + the root entity.

Fill all four fields — CoreActionName / PartsActionName / PlayRate / PlayType — and use SpriteAnimClipPlayType.Onetime for one-shot actions.

Check for conflicts with auto state transitions. On entities that have PlayerControllerComponent, MOVE/ATTACK/JUMP/... fire automatically on input — to use a custom attack, clean up the conflicting key with RemoveActionSheet or SetActionSheet (call on the server).

Split game logic into @ExecSpace("ServerOnly") and animation playback into @ExecSpace("Client").

If your goal is only to change the weapon variant of the attack motion, the simplest path is to swap the weapon-slot RUID of CostumeManagerComponent (Strategy D).