### Install Dependencies for Development

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Run this command once to install all necessary dependencies before starting development.

```bash
yarn install
```

--------------------------------

### Start the Server

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Execute this command to start the game server. Access the game at http://localhost:8098 after starting.

```bash
yarn server  # start the server
```

--------------------------------

### Install Dependencies and Build Assets

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Run these commands to install project dependencies and build the necessary assets for the application.

```bash
yarn install
yarn build   # build assets
```

--------------------------------

### Start Development Client

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Use this command to run the game client in a development environment. For a full client-server setup, run 'yarn server' and 'yarn client' in separate consoles.

```bash
yarn start
```

--------------------------------

### Start Development Server

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Run this command to start the game server for development. This is typically used in conjunction with 'yarn client'.

```bash
yarn server
```

--------------------------------

### Development Commands

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Common Yarn commands for managing the Sanguosha project, including installation, development with hot reload, server/client setup, and production builds.

```bash
# Install dependencies
yarn install

# Development with hot reload (client only)
yarn start

# Development with server
yarn server  # Terminal 1: Start server on port 8098
yarn client  # Terminal 2: Start client with proxy

# Production build
yarn build

# Run production server
yarn server

```

--------------------------------

### Start Development Client (Separate Console)

Source: https://github.com/kevinychen/sanguosha/blob/master/README.md

Run this command in a separate console to start the game client for development when the server is already running.

```bash
yarn client
```

--------------------------------

### Server Setup with FlatFile Storage

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Sets up the game server using boardgame.io with FlatFile storage for persistence. Includes automatic cleanup of old matches.

```javascript
// src/server/server.js
import { FlatFile, Server } from 'boardgame.io/server';
import path from 'path';
import serve from 'koa-static';
import { SanGuoSha } from '../lib/game';

const db = new FlatFile({ dir: 'data' });
const server = Server({
    games: [SanGuoSha],
    db,
});

const PORT = process.env.PORT || 8098;
const frontEndAppBuildPath = path.resolve(__dirname, '../../build');
server.app.use(serve(frontEndAppBuildPath));

server.run(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

// Automatic cleanup: removes matches older than 1 week
const week = 7 * 24 * 60 * 60 * 1000;
setInterval(() => {
    db.listMatches({ where: { updatedBefore: Date.now() - week } }).then(matchIDs => {
        for (const matchID of matchIDs) {
            db.wipe(matchID);
        }
    });
}, week);
```

--------------------------------

### Character Definitions Example

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Provides example definitions for game characters, including their name, country, health, gender, and optional flags like monarch or expansion. Supports over 80 characters.

```javascript
// src/lib/characters.js

// Example character definitions
const CHARACTERS = [
    {
        name: 'Liu Bei',
        country: 'Shu',
        health: 4,
        gender: 'M',
        isMonarch: true,  // Can be King
    },
    {
        name: 'Zhuge Liang',
        country: 'Shu',
        health: 3,
        gender: 'M',
        // Has Astrology ability (implemented in moves)
    },
    {
        name: 'Zhou Tai',
        country: 'Wu',
        health: 4,
        gender: 'M',
        expansion: 'wind',  // Requires Wind expansion
        // Has Refusing Death ability
    },
    {
        name: 'Dong Zhuo',
        country: 'Kingdomless',
        health: 8,
        gender: 'M',
        expansion: 'wood',
        isMonarch: true,
    },
    // ... 80+ characters across base set and expansions
];

export default CHARACTERS;

```

--------------------------------

### Initialize Sanguosha Game State

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Sets up the initial game state, including roles, characters, deck, and player hands. It returns an object containing all necessary game data.

```javascript
// src/lib/setup.js
export default function setup(ctx, setupData) {
    const { numPlayers, playOrder, random } = ctx;
    const expansions = (setupData || {}).expansions || [];

    // Returns initial game state:
    return {
        roles,
        startPlayerIndex,
        characterChoices,
        characters,
        healths,
        isAlive,
        deck,
        discard,
        hands,
        equipment,
        isChained,
        isFlipped,
        harvest,
        privateZone,
        selfZone,
        refusingDeath,
    };
}
```

--------------------------------

### Game Configuration

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Defines the core game logic, phases, and available moves. Specifies the game name, minimum and maximum players, and game phases.

```javascript
// src/lib/game.js
import { SanGuoSha } from './lib/game';

// Game configuration
SanGuoSha.name         // "san-guo-sha"
SanGuoSha.minPlayers   // 2
SanGuoSha.maxPlayers   // 10

// Game phases: 'selectCharacters' -> 'play'
// Stages during play: 'play' -> 'discard'
```

--------------------------------

### Role Distribution Configuration

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Defines the labels for roles and provides a mapping for role distribution based on the number of players. Used for balancing gameplay.

```javascript
// src/lib/roles.js

export const ROLE_DIST_LABELS = ['King', 'Rebel', 'Loyalist', 'Spy'];

// [King, Rebel, Loyalist, Spy] counts per player count
export const ROLE_DIST = {
    2:  [1, 1, 0, 0],
    3:  [1, 1, 0, 1],
    4:  [1, 2, 0, 1],
    5:  [1, 2, 1, 1],
    6:  [1, 3, 1, 1],
    7:  [1, 3, 2, 1],
    8:  [1, 4, 2, 1],
    9:  [1, 4, 3, 1],
    10: [1, 5, 3, 1],
};

```

--------------------------------

### Client Lobby Management

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Handles match creation, joining, and player management using boardgame.io's LobbyClient. Allows creating new matches, joining existing ones, and listing active matches.

```javascript
// src/client/lobby.js
import { LobbyClient } from 'boardgame.io/client';
import { SocketIO } from 'boardgame.io/multiplayer';
import { Client } from 'boardgame.io/react';
import { SanGuoSha } from '../lib/game';
import { SanGuoShaBoard } from './board';

const SERVER = process.env.REACT_APP_PROXY || document.location.toString().replace(///$/, '');
const EXPANSIONS = ['wind', 'fire', 'wood', 'knight11', 'hill', 'sp11', 'knight12'];

const SanGuoShaClient = Client({
    game: SanGuoSha,
    board: SanGuoShaBoard,
    multiplayer: SocketIO({ server: SERVER }),
    debug: false,
});

// Create a new match
const lobbyClient = new LobbyClient({ server: SERVER });
const { matchID } = await lobbyClient.createMatch(SanGuoSha.name, {
    numPlayers: 4,
    setupData: {
        expansions: ['wind', 'fire'], // Optional expansions
    },
});

// Join match as a player
const { playerCredentials } = await lobbyClient.joinMatch(SanGuoSha.name, matchID, {
    playerID: '0',
    playerName: 'Player1',
});

// Leave match
await lobbyClient.leaveMatch(SanGuoSha.name, matchID, {
    playerID: '0',
    credentials: playerCredentials,
});

// List all active matches
const { matches } = await lobbyClient.listMatches(SanGuoSha.name);
```

--------------------------------

### Sanguosha Game Moves: Turn Management

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions to manage the game turn phases. Use `endPlay` to end the action phase, `discardCard` to discard during the discard phase, and `finishDiscard` to force the end of the discard phase.

```javascript
// Turn management
Moves.endPlay();                           // End action phase
Moves.discardCard(index);                  // Discard during discard phase
Moves.finishDiscard();                     // Force end discard phase
```

--------------------------------

### Sanguosha Game Moves: Card Visibility

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions to control card visibility and state. Use `reveal` to show a card to another player, `returnCard` to bring it back, and `flipObject` to change its face-up/down state.

```javascript
// Card visibility
Moves.reveal(handIndex, otherPlayerID);    // Reveal card to specific player
Moves.returnCard(cardID);                  // Return revealed card to hand
Moves.flipObject(objectID);                // Flip card/character face up/down
```

--------------------------------

### Card Categories Definitions

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Defines basic card types and maps equipment cards to their categories. Includes weapons, shields, and horses with their effects.

```javascript
// src/lib/cardCategories.js

// Basic card types
export const BASIC = ['Attack', 'Escape', 'Peach', 'Fire Attack', 'Lightning Attack', 'Wine'];

// Equipment categories mapped by card type
export const EQUIPMENT = {
    // Delay tools (judgment cards)
    'Lightning': 'Lightning',
    'Capture': 'Capture',
    'Starvation': 'Starvation',

    // Weapons (range: 1-5)
    'Crossbow': 'Weapon',          // Range 1, unlimited attacks
    'Black Pommel': 'Weapon',      // Range 2, ignores armor
    'Ice Sword': 'Weapon',         // Range 2, freeze effect
    'Green Dragon Blade': 'Weapon', // Range 3, chain attacks
    'Serpent Spear': 'Weapon',     // Range 3, discard for attack
    'Axe': 'Weapon',               // Range 3, force hit
    'Sky Scorcher': 'Weapon',      // Range 4, multi-target
    'Longbow': 'Weapon',           // Range 5, destroy horses

    // Shields/Armor
    'Eight Trigrams': 'Shield',    // Judgment for free escape
    'Black Shield': 'Shield',      // Immune to black attacks
    'Wood Armor': 'Shield',        // AOE immunity, fire weakness
    'Silver Helmet': 'Shield',     // Damage cap, heal on loss

    // Horses (distance modifiers)
    'Red Hare': '-1',      // Offensive horse
    'Da Yuan': '-1',
    'Zi Xing': '-1',
    'Di Lu': '+1',         // Defensive horse
    'Shadow Runner': '+1',
    'Storm Runner': '+1',
    'Hua Liu': '+1',
};

```

--------------------------------

### Draw and Discard Card Logic

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Handles drawing cards, reshuffling the discard pile if the deck is empty, and discarding cards. Ensures deck integrity during card operations.

```javascript
// src/lib/helper.js

// Draw a single card, auto-reshuffling discard if deck empty
export function drawCard(G, ctx) {
    const { deck, discard, isFlipped } = G;
    const { random } = ctx;

    const card = deck.pop();
    if (card === undefined) return;

    if (deck.length === 0) {
        deck.push(...random.Shuffle(discard.splice(0, discard.length)));
    }
    if (isFlipped[card.id]) {
        delete isFlipped[card.id];
    }
    return card;
}

// Draw multiple cards for a specific player
export function drawCards(G, ctx, playerID, count) {
    const { hands } = G;
    for (let i = 0; i < count; i++) {
        const card = drawCard(G, ctx);
        if (card === undefined) return;
        hands[playerID].push(card);
    }
}

// Discard a card, auto-reshuffling if deck empty
export function discard(G, ctx, card) {
    const { deck, discard } = G;
    const { random } = ctx;

    discard.push(card);
    if (deck.length === 0) {
        deck.push(...random.Shuffle(discard.splice(0, discard.length)));
    }
}
```

--------------------------------

### Find Next Alive Player Position

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Calculates the position of the next alive player in a circular manner. Useful for turn-based game flow.

```javascript
// src/lib/helper.js

// Find next alive player position (circular)
export function nextAlivePlayerPos(G, ctx, pos) {
    const { isAlive } = G;
    const { numPlayers, playOrder } = ctx;
    let newPos = pos;
    do {
        newPos = (newPos + 1) % numPlayers;
    } while (!isAlive[playOrder[newPos]]);
    return newPos;
}
```

--------------------------------

### Sanguosha Game Moves: Character Abilities

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions for character-specific abilities. Includes Zhuge Liang's astrology, Lu Su's alliance (hand swap), and Dong Zhuo's collapse (reduce max health).

```javascript
// Character abilities
Moves.astrology(numCards);                 // Zhuge Liang: view top cards
Moves.finishAstrology();                   // Complete astrology rearrangement
Moves.alliance(player1, player2);          // Lu Su: swap player hands
Moves.collapse();                          // Dong Zhuo: reduce max health
```

--------------------------------

### Sanguosha Game Moves: Drawing Cards

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions to draw cards from the deck or perform a judgment draw. Use `moves.draw()` for a single card and `moves.judgment()` for a draw-and-discard action.

```javascript
// Drawing cards
moves.draw();                              // Draw one card from deck
moves.judgment();                          // Draw and discard (judgment)
```

--------------------------------

### Sanguosha Game Moves: Special Actions

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions for special game actions like Harvest, picking up from harvest, toggling chain status, and passing lightning.

```javascript
// Special actions
Moves.harvest();                           // Draw cards for all players (Harvest)
Moves.pickUpHarvest(index);                // Pick card from harvest display
Moves.toggleChain();                       // Toggle chain status
Moves.passLightning();                     // Pass Lightning to next player
```

--------------------------------

### Sanguosha Game Moves: Card Interactions

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions for interacting with other players' cards, including giving, stealing, and dismantling. Specify target player and card index or category.

```javascript
// Card interactions
Moves.give(handIndex, otherPlayerID);      // Give card to another player
Moves.steal({ playerID, index });          // Steal random hand card
Moves.steal({ playerID, category });       // Steal equipment by category
Moves.dismantle({ playerID, index });      // Discard target's hand card
Moves.dismantle({ playerID, category });   // Discard target's equipment
```

--------------------------------

### Sanguosha Game Moves: Playing Cards

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions to play cards from a player's hand. Can be used to play general cards, equipment on a target, or force a card category.

```javascript
// Playing cards
moves.play(handIndex);                     // Play card from hand
Moves.play(handIndex, targetPlayerID);     // Play equipment on target
Moves.play(handIndex, targetPlayerID, 'Capture');  // Force card category
```

--------------------------------

### Sanguosha Game Moves: Health Management

Source: https://context7.com/kevinychen/sanguosha/llms.txt

Functions to adjust player health and status. Includes decreasing/increasing health, modifying max health, and removing a player from the game.

```javascript
// Health management
Moves.updateHealth(-1);                    // Decrease health
Moves.updateHealth(+1);                    // Increase health (heal)
Moves.updateMaxHealth(-1);                 // Reduce max health
Moves.die();                               // Remove player from game
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.