masoi-role-designer

name	masoi-role-designer
description	Design and integrate new roles into Ma Sói Online. Provides templates, file checklists, balance guidelines, and integration patterns for adding roles across server game engine, socket handlers, client hooks, UI components, and documentation. Use when planning, implementing, or reviewing new character roles.

Ma Sói Role Designer

Workflow

1. Define role concept: name, team, emoji, description, night action (if any), passive (if any), trigger conditions.
2. Check balance against existing roles using references/role-template.md.
3. Implement server-side:
   • Add to ROLES object in server/gameEngine.js.
   • Update getRoleConfig() distribution logic.
   • Add night action handler in server/index.js → night_action.
   • Add to checkNightComplete() if role has night action.
   • Add to resolveNight() or resolveVote() if role has special triggers.
   • Update isWolf() helper if new wolf-team role.
4. Implement client-side:
   • Add night UI in client/src/pages/NightPhase.jsx.
   • Add any special prompts or result displays.
   • Update client/src/hooks/useGame.js for new socket events.
   • Update client/src/pages/GuidePage.jsx with role description.
   • Update client/src/pages/WaitingRoom.jsx role config UI.
5. Update documentation:
   • Update docs/GAME_LOGIC.md with role behavior and socket events.
   • Update README.md role table.
6. Verify:
   • node --check server/index.js
   • node --check server/gameEngine.js
   • cd client && npm run build

Balance Guidelines

• Wolf team should always be less than half the players.
• Max 3 wolves total (including wolf variants).
• Each village special role should have clear counterplay (wolves can target them).
• Avoid roles that create unfun "kingmaker" dynamics (one player decides the game with no risk).
• New night-action roles increase night duration — consider timer impact.
• Passive roles (like IDIOT) are simpler to implement but still need edge case testing.

File Modification Checklist

When adding a new role, you MUST touch these files:

Server (Required)

File	What to Add
server/gameEngine.js	ROLES entry, getRoleConfig() logic, update sanitizeCustomRoles()
server/index.js	Night action handler, skip handler, resolution logic, reconnect state

Client (Required)

File	What to Add
client/src/pages/NightPhase.jsx	Night UI panel, target selection, confirm button
client/src/hooks/useGame.js	New socket event listeners, state variables, action emitters
client/src/pages/GuidePage.jsx	Role description in guide
client/src/pages/WaitingRoom.jsx	Role in custom config picker

Documentation (Required)

File	What to Add
docs/GAME_LOGIC.md	Role behavior section, socket events, edge cases
README.md	Role table entry

Optional

File	When Needed
client/src/components/RoleCard.jsx	If role has unique visual treatment
client/src/pages/ResultScreen.jsx	If role has special end-game display
client/src/pages/DayPhase.jsx	If role has day-phase actions

References

Load references/role-template.md when designing or implementing a new role.