From 482618a4edb96ab1d49f708031dc667a85858280 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 29 Aug 2025 12:48:39 +0000 Subject: [PATCH] Add comprehensive GitHub Copilot instructions for Fantasy Map Generator Co-authored-by: Azgaar <26469650+Azgaar@users.noreply.github.com> --- .github/copilot-instructions.md | 165 ++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..ec105019 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,165 @@ +# Fantasy Map Generator +Azgaar's Fantasy Map Generator is a client-side JavaScript web application for creating fantasy maps. It's a 41MB repository with 232 JavaScript files that 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 +- **CRITICAL**: This is a static web application - NO build process needed. No npm install, no compilation, no bundling. +- Run the application using HTTP server (required - cannot run with file:// protocol): + - **Python (Recommended)**: `python3 -m http.server 8000` - takes 2-3 seconds to start + - **Alternative**: `./run_python_server.sh` or `./run_python_server.bat` + - **Docker**: `docker build -t fmg . && docker run -p 8001:80 fmg` - build takes 3-5 minutes, run takes 3 seconds +- Access at: `http://localhost:8000` (Python) or `http://localhost:8001` (Docker) +- **Map Generation Time**: ~0.76 seconds for complete fantasy world generation. NEVER CANCEL generation. + +## Validation +- Always manually validate any changes by: + 1. Starting the HTTP server (NEVER CANCEL - wait for full startup) + 2. Navigate to the application in browser + 3. Click the "►" button to 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 +- **Expected Behavior**: Map generation shows console logs ending with "TOTAL: ~0.76s" and displays colorful political map with kingdoms, empires, cities, and geographic features +- **Known Issues**: Google Analytics and font loading errors are normal (blocked external resources) + +## Repository Structure +### Core Files +- `index.html` - Main application entry point (589KB) +- `main.js` - Core application logic (1,268 lines) +- `versioning.js` - Version management and update handling + +### Key Directories +- `modules/` - Core functionality modules: + - `modules/ui/` - 44 UI components (editors, tools, style management) + - `modules/dynamic/` - Runtime modules (export, installation) + - `modules/renderers/` - Drawing and rendering logic +- `utils/` - 15 utility libraries (math, arrays, strings, etc.) +- `styles/` - 12 visual style presets (JSON files) +- `libs/` - Third-party libraries (D3.js, TinyMCE, etc.) +- `images/` - Icons, backgrounds, UI elements +- `charges/` - Heraldic symbols and coat of arms elements + +### Configuration & Assets +- `config/` - Heightmap templates and configurations +- `heightmaps/` - Terrain generation data +- `components/` - UI component definitions + +## Deployment Options +### Python HTTP Server (Recommended for Development) +```bash +cd /path/to/Fantasy-Map-Generator +python3 -m http.server 8000 +# Access: http://localhost:8000 +``` + +### Docker (Recommended for Production) +```bash +cd /path/to/Fantasy-Map-Generator +docker build -t fantasy-map-generator . # Takes 3-5 minutes +docker run -p 8001:80 fantasy-map-generator # Takes 3 seconds +# Access: http://localhost:8001 +``` + +### Shell Scripts (Alternative) +```bash +# Linux/macOS +./run_python_server.sh + +# Windows +./run_python_server.bat +./run_php_server.bat # PHP alternative +``` + +## Common Tasks +### Making Code Changes +1. Edit JavaScript files directly (no compilation needed) +2. Refresh browser to see changes immediately +3. **ALWAYS test map generation** after making changes +4. Update version in `versioning.js` if making significant changes +5. Update file hashes in `index.html` for changed files (format: `file.js?v=1.108.1`) + +### Debugging Map Generation +- Open browser developer tools console +- Look for timing logs: "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 + +## Important Locations +### Frequently Modified Files +- `main.js` - Core map generation logic +- `modules/ui/layers.js` - Layer management and visualization +- `modules/heightmap-generator.js` - Terrain generation +- `modules/burgs-and-states.js` - Political entity generation +- `modules/ui/style.js` - Visual styling controls +- `versioning.js` - Update management + +### Key Reference Files +```bash +# Repository structure +ls -la /path/to/repo +. +.. +main.js # Core application (1,268 lines) +index.html # Entry point (589KB) +versioning.js # Version management +modules/ # 25+ core modules +utils/ # 15 utility libraries +styles/ # 12 style presets +libs/ # Third-party dependencies +Dockerfile # Container deployment +``` + +### Quick File Lookup +```bash +# Main application files +find . -name "main.js" # Core logic +find . -name "index.html" # Entry point +find . -name "versioning.js" # Version info + +# UI and editor files +find ./modules/ui -name "*editor.js" # All editors +find ./modules/ui -name "layers.js" # Layer controls +find ./modules/ui -name "style.js" # Style controls + +# Generation modules +find ./modules -name "*generator.js" # All generators +find ./modules -name "heightmap-generator.js" # Terrain +find ./modules -name "burgs-and-states.js" # Politics +``` + +## Performance Notes +- Map generation: ~0.76 seconds typical +- Application startup: 2-3 seconds +- Repository size: 41MB total +- JavaScript files: 232 total +- NEVER CANCEL map generation or server startup processes + +## Troubleshooting +### Application Won't Load +- Ensure using HTTP server (not file://) +- Check console for JavaScript errors +- Verify all files are present in repository + +### Map Generation Fails +- Check browser console for error messages +- Look for specific module failures in generation logs +- Try refreshing page and generating new map + +### Performance Issues +- Map generation should complete in ~1 second +- If slower, check browser console for errors +- Large maps or complex configurations may take longer + +## DO NOT +- Do not attempt to build or compile the application +- Do not look for package.json or build tools (none exist) +- Do not cancel map generation process +- Do not run without HTTP server (will fail with security errors) + +Remember: This is a sophisticated client-side application that generates complete fantasy worlds with political systems, geography, cultures, and detailed cartographic elements. Always validate that your changes preserve the core map generation functionality. \ No newline at end of file