# Masoi Role Designer

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

- Skill: `nobodyonlyc/masoi-role-designer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nobodyonlyc/masoi-role-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nobodyonlyc/masoi-role-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: nobodyonlyc (https://skillmd.com/u/nobodyonlyc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nobodyonlyc/masoi-role-designer

---


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