Game-specific extensions and utilities for the Boardcast hex board animation library.

The contrib library provides specialized methods for visualizing and animating game mechanics specific to different tabletop game systems. Each game system is organized into its own module with methods that extend the core Boardcast functionality.

RPG mech combat system with movement, engagement, and terrain mechanics.

• Movement: Speed-based movement ranges, boost actions, terrain effects
• Combat: Engagement zones, weapon ranges, line of sight, blast templates

import { BoardcastHexBoard } from 'boardcast';
import { Lancer } from 'boardcast/contrib';

const board = new BoardcastHexBoard();
const movement = new Lancer.LancerMovement(board);
const combat = new Lancer.LancerCombat(board);

// Show movement range for a speed 4 mech at (0,0)
movement.showMovementRange(0, 0, 4);

// Show engagement zone around mech
combat.showEngagementZone(0, 0);

To contribute a new game system (e.g., "MyGame"):

contrib/
└── mygame/
    ├── index.ts       # Main exports
    ├── types.ts       # Game-specific types
    ├── movement.ts    # Movement mechanics (if applicable)
    ├── combat.ts      # Combat mechanics (if applicable)
    └── [feature].ts   # Other game features

// contrib/mygame/types.ts
export interface MyGameUnit {
  id: string;
  name: string;
  // Game-specific properties
}

// contrib/mygame/movement.ts
import { BoardcastHexBoard } from '../../lib/BoardcastHexBoard.js';

export class MyGameMovement {
  constructor(private board: BoardcastHexBoard) {}

  showMovementPattern(q: number, r: number): void {
    // Use board.highlight(), board.pulse(), etc.
  }
}

// contrib/mygame/index.ts
export { MyGameMovement } from './movement.js';
export type { MyGameUnit } from './types.js';

// contrib/index.ts
export * as MyGame from './mygame/index.js';

• Descriptive Names: Use clear, game-specific method names
• Flexible Parameters: Support customization (colors, ranges, etc.)
• Return Values: Return useful data when appropriate
• Documentation: Include JSDoc comments with examples

• Use Colors constants from core library when possible
• Follow existing animation patterns (pulse for ranges, blink for threats)
• Provide sensible color defaults but allow customization

/**
 * Show special game mechanic visualization
 * @param centerQ - Center hex q coordinate
 * @param centerR - Center hex r coordinate
 * @param options - Customization options
 */
showSpecialMechanic(
  centerQ: number, 
  centerR: number, 
  options: { color?: string; size?: number } = {}
): GameMechanicResult {
  const { color = Colors.BLUE, size = 1 } = options;
  
  // Implementation using board methods
  this.board.highlight(centerQ, centerR, color);
  
  return { /* useful data */ };
}

• One class per file for complex features
• Related utilities can share files
• Export everything from module index
• Import paths should use .js extension for ES modules

# Build contrib library
npm run build:contrib

# Build everything (lib + contrib + demo)
npm run build

# Type checking
npm run typecheck

# Run tests
npm run test

Core library methods are available on the board instance:

board.highlight(q, r, color);     // Core method
board.pulse(q, r, color);         // Core method
board.token(q, r, name, ...);     // Core method

Contrib methods are organized by game system:

const movement = new Lancer.LancerMovement(board);
movement.showMovementRange(q, r, speed);  // Contrib method

This separation keeps the core library lightweight while allowing rich game-specific functionality in contrib modules.