Fantasy-Map-Generator/.github/copilot-instructions.md

Fantasy Map Generator

Azgaar's Fantasy Map Generator is a web application for creating fantasy maps. It generates detailed fantasy worlds with countries, cities, rivers, biomes, and cultural elements.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

• The project uses NPM, Vite, and TypeScript for development and building.
• Setup: Run npm install to install dependencies (requires Node.js >= 24.0.0)
• Development: Run npm run dev to start the Vite development server
  • Access at: http://localhost:5173 (Vite's default port)
  • Hot module replacement (HMR) enabled - changes are reflected immediately
• Building: Run npm run build to compile TypeScript and build for production
  • TypeScript compilation runs first (tsc)
  • Vite builds the application to dist/ directory
• Preview: Run npm run preview to preview the production build locally

Validation

• Always manually validate any changes by:
  1. Run npm run dev to start the development server (wait for "ready" message)
  2. Navigate to the application in browser (typically http://localhost:5173)
  3. Click the "►" button to open the menu and generate a new map
  4. CRITICAL VALIDATION: Verify the map generates with countries, cities, roads, and geographic features
  5. Test UI interaction: click "Layers" button, verify layer controls work
  6. Test regeneration: click "New Map!" button, verify new map generates correctly
• Known Issues: Google Analytics and font loading errors are normal (blocked external resources)
• For production build validation: run npm run build followed by npm run preview

Repository Structure

Core Files

• package.json - NPM package configuration with scripts and dependencies
• vite.config.ts - Vite build configuration
• tsconfig.json - TypeScript compiler configuration

Source Directories

• src/ - Source code directory (build input)
  • src/index.html - Main application entry point
  • src/utils/ - TypeScript utility modules (migrated from JS)
• public/ - Static assets (copied to build output)
  • public/main.js - Core application logic
  • public/versioning.js - Version management and update handling
  • public/modules/ - Core functionality modules:
    • modules/ui/ - UI components (editors, tools, style management)
    • modules/dynamic/ - runtime modules (export, installation)
    • modules/renderers/ - drawing and rendering logic
  • public/styles/ - Visual style presets (JSON files)
  • public/libs/ - Third-party libraries (D3.js, TinyMCE, etc.)
  • public/images/ - Backgrounds, UI elements
  • public/charges/ - Heraldic symbols and coat of arms elements
  • public/config/ - Heightmap templates and configurations
  • public/heightmaps/ - Terrain generation data
• dist/ - Production build output (generated by npm run build)

Common Tasks

Making Code Changes

1. TypeScript files (src/utils/*.ts):
   • Edit TypeScript files in the src/utils/ directory
   • Changes are automatically recompiled and hot-reloaded in dev mode
   • Run npm run build to verify TypeScript compilation succeeds
2. JavaScript files (public/*.js, public/modules/*.js):
   • Edit JavaScript files directly in the public/ directory
   • Changes are automatically reflected in dev mode via HMR
   • Note: Core application logic is still in JavaScript and gradually being migrated
3. Always test map generation after making changes
4. Update version in public/versioning.js for all changes
5. For production builds, update file hashes in src/index.html if needed (format: file.js?v=1.108.1)

Debugging Map Generation

• Open browser developer tools console
• Look for timing logs, e.g. "TOTAL: ~0.76s"
• Map generation logs show each step (heightmap, rivers, states, etc.)
• Error messages will indicate specific generation failures

Testing Different Map Types

• Use "New Map!" button for quick regeneration
• Access "Layers" menu to change map visualization
• Available presets: Political, Cultural, Religions, Biomes, Heightmap, Physical, Military

Troubleshooting

Application Won't Load

• Run npm install to ensure dependencies are installed
• Run npm run dev to start the development server
• Check console for JavaScript/TypeScript errors
• Verify all files are present in repository
• Ensure Node.js version >= 24.0.0 (node --version)

Build Failures

• Check TypeScript compilation errors (tsc output)
• Verify all dependencies are installed (npm install)
• Check tsconfig.json for configuration issues
• Look for import/module resolution errors

Map Generation Fails

• Check browser console for error messages
• Look for specific module failures in generation logs
• Try refreshing page and generating new map
• Verify build completed successfully if using production build

Performance Issues

• Map generation should complete in ~1 second for standard configurations
• If slower, check browser console for errors
• Development mode may be slower due to HMR overhead

Remember: This is a sophisticated application that generates complete fantasy worlds with political systems, geography, cultures, and detailed cartographic elements. The project is gradually migrating from vanilla JavaScript to TypeScript. Always validate that your changes preserve the core map generation functionality.