A client-side web app for generating DarkSpace characters.
The DarkSpacers Character Generator is a React-based web application that helps players create characters for the DarkSpace RPG. It features:
- Random Character Generation: Generate complete characters with the click of a button
- Interactive Components: Manually select and customize character attributes
- PDF Export: Generate character sheets as PDF documents
- Responsive Design: Material-UI components for a modern, mobile-friendly interface
- Redux State Management: Centralized state management for complex character data
- Frontend: React 19.1.0 with TypeScript
- UI Framework: Material-UI (MUI) 7.0.2 with Emotion styling
- State Management: Redux Toolkit 2.8.2 with React-Redux
- Testing: Jest 27.5.1 with React Testing Library
- Build Tool: Create React App with React Scripts
- PDF Generation: pdf-lib 1.17.1
- Internationalization: i18next and react-i18next
DarkSpacersSite/
โโโ LICENSE
โโโ README.md
โโโ darkspacer-site/
โโโ .gitignore
โโโ jest.config.js
โโโ package.json
โโโ package-lock.json
โโโ tsconfig.json
โโโ public/ # Public static assets
โ โโโ index.html
โ โโโ manifest.json
โ โโโ robots.txt
โ โโโ DarkSpace.png
โ โโโ SpacerSheet.pdf
โโโ src/
โ โโโ App.tsx
โ โโโ App.test.tsx
โ โโโ index.tsx
โ โโโ setupTests.ts
โ โโโ app/ # Redux store and hooks
โ โโโ assets/
โ โโโ data/ # Game rule JSON files
โ โโโ generators/ # Generation logic + tests
โ โโโ models/
โ โ โโโ rules/
โ โ โโโ view/
โ โโโ repository/ # Data access layer + tests
โ โโโ slices/ # Redux slices/state generators
โ โโโ utils/ # Utility functions + tests
โ โโโ views/ # React views/components
โ โโโ ability-scores/
โ โโโ archetype/
โ โโโ background/
โ โโโ character-name/
โ โโโ character-species/
โ โโโ common/
โ โโโ motivation/
โ โโโ summary/
- Models (
src/models/): TypeScript classes defining game entitiesBackground: Character background informationArchetype: Character classes and abilitiesAbilityScore: Character statisticsTrait: Species-specific characteristics
- Abstraction layer for accessing JSON data files
- Repositories for: Archetypes, Backgrounds, Items, Motivations, Names, Traits
- Implements repository pattern for data access
- AbilityScoreGenerator: Handles dice rolling mechanics (3d6, 4d6 drop lowest)
- ArchetypeGenerator: Selects character classes and abilities
- RandomNumberGenerator: Core RNG implementation
- ThingPicker/RangedThingPicker: Generic selection utilities
- Redux Toolkit slices managing different aspects of character state
- Primary slice:
characterSlice.ts- Central character data management
- DesignCharacter: Main character creation interface
- AbilityScoresComponent: Ability score generation and display
- BackgroundComponent: Background selection
- CharacterSpeciesComponent: Species selection and traits
- ArchetypeSelector: Class and archetype selection
- GearSelector: Equipment and gear management
- Node.js (version 16 or higher)
- npm or yarn package manager
-
Clone the repository:
git clone <repository-url> cd DarkSpacersSite/darkspacer-site
-
Install dependencies:
npm install
Start the development server with hot reloading:
npm startThe application will open at http://localhost:3000.
Create an optimized production build:
npm run build-
Local build (for localhost deployment):
npm run build-local
-
Shape build (for shapeshifting.org deployment):
npm run build-shape
The build process creates:
- Minified JavaScript and CSS bundles
- Static assets (images, fonts, manifest files)
index.htmlwith proper resource references- Source maps for debugging
Execute the test suite:
npm testThis command:
- Runs tests in watch mode during development
- Executes all
.test.tsand.test.tsxfiles - Provides coverage reports
- Uses Jest with React Testing Library
- Jest Config: Custom configuration in
jest.config.js - Test Environment: Node.js with DOM simulation
- Test Utilities: React Testing Library, Jest mocks
- Coverage: Available through Jest's built-in coverage reporting
Tests are co-located with source files following the pattern:
Component.test.tsxfor React component testsService.test.tsfor business logic tests- Example:
AbilityScoreGenerator.test.tstests dice rolling mechanics
The application implements several DarkSpace RPG systems:
- Standard: 3d6 per ability
- Heroic: 4d6, drop lowest per ability (Not really used with Shadowdark so I'll probably axe it soon.)
- Six core abilities: STR, DEX, CON, INT, WIS, CHA
- Species Selection: Choose character species with associated traits
- Background: Random or manual background selection
- Archetype: Class selection with talents and abilities
- Ability Scores: Generate or assign ability scores
- Motivation: Character motivation and goals
- Gear: Starting equipment selection
Game rules are stored in JSON files (src/data/):
Archetype.json: Character classes and abilitiesBackground.json: Character backgroundsTrait.json: Species traits and modifiersItem.json: Equipment and gearNames.json: Character name generators
The application uses Redux Toolkit for state management:
// Central character state
interface CharacterState {
name: string;
abilityScores: AbilityScore[];
background: Background;
archetype: Archetype;
species: Species;
// ... other character properties
}State is managed through:
- Actions: Dispatched from UI components
- Reducers: Pure functions updating state
- Selectors: Derived state and computed values
The application supports multiple deployment targets:
- Local Development: Standard React development server
- Static Hosting: Build outputs can be served from any static host
- Custom Domains: Configurable public URL through build scripts
- Public URL: Configurable via
PUBLIC_URLenvironment variable - Asset Paths: Relative paths for portability
- Build Optimization: Production builds are minified and optimized
- package.json: Dependencies and build scripts
- App.tsx: Main application component
- store.ts: Redux store configuration
- DesignCharacter.tsx: Primary character creation interface
- jest.config.js: Test configuration
- tsconfig.json: TypeScript configuration
- Follow TypeScript best practices
- Maintain test coverage for new features
- Use Material-UI components for consistency
- Follow Redux Toolkit patterns for state management
- Ensure responsive design principles
This project is licensed under the ISC License.