# Skyla Original Games - AI Coding Instructions

## Overview
This is a casino game platform providing 20+ blockchain games (Crash, Dice, Limbo, etc.) via an NPM package. The architecture uses adapter pattern to decouple games from platform-specific wallet/database logic.

## Key Architecture Concepts

### GamePlatformAdapter Pattern
The heart of the system is `GamePlatformAdapter.js` - an abstract class that defines 17+ methods for wallet operations, bet management, and user lookups. 

- **Default behavior**: Falls back to legacy `Users/Rule` module for backward compatibility
- **Integration**: Host platforms extend this adapter to wire their own database/wallet systems
- **Standalone testing**: Use `StandaloneAdapter` for in-memory testing without external dependencies

```js
// Essential integration pattern
const adapter = new MyPlatformAdapter(); 
OriginalGames.setGamePlatformAdapter(adapter);
```

### Configuration System
Environment-driven configuration with runtime overrides:
- **Environment variables**: `ORIGINAL_GAMES_*` prefixed vars (see `CONFIGURATION.md`)
- **Runtime config**: `OriginalGames.setGameConfig()` for programmatic overrides
- **Immutable defaults**: `DEFAULT_GAME_CONFIG` in `configuration/defaults.js`

### Game Structure Pattern
All games follow consistent patterns in `Games/*/index.js`:
- Export object with game-specific methods (not classes)
- Use `getGamePlatformAdapter()` to access wallet operations
- Import shared utilities from `General/` (Buffer, Socket, Helper, Constant)
- Stateful games like Crash maintain module-level state variables

## Critical Developer Workflows

### Running Tests
```bash
npm test  # Uses Jest, includes wager flow integration tests
```

### Crash Game Service
Crash requires a background service loop. Initialize with:
```js
const crashService = OriginalGames.initializeCrashService({
  io: socketIoServer,
  platformAdapter: myAdapter,
  registerShutdown: (stopFn) => { /* handle SIGTERM */ }
});
```

### HTTP Server Bootstrap
For standalone/testing scenarios:
```js
const { app, server, adapter } = OriginalGames.createHttpServer({
  adapterOptions: { /* StandaloneAdapter config */ }
});
```

## Project-Specific Conventions

### Module Exports
- Main entry (`index.js`) exports games both as `Game.X` properties and root-level exports
- Game catalog available as both `gameCatalog` and `games`
- Configuration helpers exported at multiple levels for compatibility

### Socket Event Handling
- Game events defined in `Games/eventHandlers.js`
- Use `createGameSession({ io, adapter })` to wire socket events to adapter
- Buffer encoding/decoding via `General/Buffer`

### File Organization
- `Games/`: Individual game implementations + shared utilities
- `General/`: Cross-game utilities (Buffer, Queue, Socket, Helper, Constant) 
- `adapters/`: Platform adapter implementations
- `services/`: Background services (crash loop, HTTP bootstrap)
- `configuration/`: Config resolution and defaults

### Bot Integration
Games support bot seeding via adapter's `getBots(game, hour, callback)` method. Bots treated as special users in game logic but tracked separately in profit calculations.

## Integration Points

### Legacy Backend Compatibility
Package designed to replace `backend/Games` while maintaining API compatibility. Games can run standalone or integrated with existing Skyla backend via `UsersRuleAdapter`.

### Asset Management
Game catalog (`Games/list.js`) includes asset paths expecting CDN hosting. Configure `ORIGINAL_GAMES_ASSET_URL` for production deployments.

### Database Requirements
- PostgreSQL for game history (Crash service dependency check)
- Redis for queue/state management (optional, via `General/Queue/Redis.js`)
- Platform adapter handles all wallet/balance persistence