msw-avatar

Manages MapleStory Worlds avatar costumes and animation state mappings via file edits and scripts.

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/yoongang02/MapleFist --skill msw-avatar-yoongang02
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: msw-avatar
Source: https://github.com/yoongang02/MapleFist/tree/main/.agents/skills/msw-avatar
Command: npx skills add https://github.com/yoongang02/MapleFist --skill msw-avatar-yoongang02

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Configuring avatar appearance and animation in MapleStory Worlds is error-prone: 17 costume slots have mutual-exclusion rules, four different naming levels exist for animation states, and the engine's auto-playback silently overwrites custom actions. This Skill documents the exact component properties, mapping tables, and event APIs needed to control costumes and animations correctly. ## Core Features & Use Cases - Costume management: Read and write the 17 Custom*Equip slots of CostumeManagerComponent in DefaultPlayer.model or .map files, including longcoat/two-handed weapon slot-occupancy rules and UseCustomEquipOnly. - Animation state mapping: Configure AvatarStateAnimationComponent (IsLegacy, ActionSheet, StateToAvatarBodyActionSheet) and understand the State key → MapleAvatarBodyActionState → sprite action ID pipeline. - Custom action playback: Play arbitrary sprite action IDs like shoot1 or swingO2 via ActionStateChangedEvent on the body entity, and resolve auto-playback conflicts with RemoveActionSheet/SetActionSheet. - Use Case: You want the player to fire a bow with the shoot1 animation instead of the default sword swing. Remove the ATTACK mapping on the server, then send an ActionStateChangedEvent with shoot1 to the body entity on the client. ## Quick Start Ask the AI to change the DefaultPlayer's equipped weapon to a bow and make the attack input play the shoot1 animation instead of the default sword swing.

Frequently Asked Questions about msw-avatar

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I change a player avatar's equipment in MapleStory Worlds?

Edit the CostumeManagerComponent properties in DefaultPlayer.model or the entity's .map file, setting Custom*Equip string fields to avatar item RUIDs. After saving, call the msw-maker-mcp refresh tool so the editor picks up the change.

How do I play a custom animation like shoot1 on an MSW avatar?

Get the body entity via AvatarRendererComponent:GetBodyEntity(), then send an ActionStateChangedEvent with CoreActionName and PartsActionName set to the sprite action ID. Run it in a Client ExecSpace and use Onetime play type for one-shot actions.

Why does my custom avatar animation get overwritten immediately?

While a State like ATTACK is active, AvatarStateAnimationComponent continuously re-sends its mapped body motion, overwriting single-shot events. Call RemoveActionSheet("ATTACK") on the server or change the mapping with SetActionSheet to stop the auto playback.

What is the difference between ActionStateChangedEvent and BodyActionStateChangeEvent?

ActionStateChangedEvent plays arbitrary sprite action IDs like shoot1 and is sent to the body entity. BodyActionStateChangeEvent targets one of the 14 built-in MapleAvatarBodyActionState enum values and is sent to the avatar root entity.

Can I equip a longcoat and pants at the same time in MSW?

No. Longcoat occupies both the Coat and Pants slots, so put the RUID in CustomLongcoatEquip and leave coat and pants empty. Similarly, two-handed weapons occupy both the one-handed weapon and sub-weapon slots.

Why does SetColor on SpriteRendererComponent not affect my avatar?

SpriteRendererComponent.Color and FlipX are silent no-ops on avatar entities because AvatarRendererComponent paints over the sprite output. Use AvatarRendererComponent:SetColor, SetAlpha, or SetAvatarPartColor instead.