mirror of
https://github.com/Azgaar/Fantasy-Map-Generator.git
synced 2026-03-23 23:57:23 +01:00
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# Fantasy Map Generator — Global Variable Architecture
|
|
|
|
## Critical: main.js is NOT an ES Module
|
|
|
|
`public/main.js` (and all other `public/modules/**/*.js` files) are loaded as plain
|
|
`<script defer>` tags — **not** ES modules. Every `var`, `let`, `const`, and `function`
|
|
declaration at the top level of these files is automatically a **property of `window`**
|
|
(the global object).
|
|
|
|
### Key globals exposed by main.js
|
|
|
|
| Variable | Type | Description |
|
|
| ------------- | ----------------- | -------------------------------------------- |
|
|
| `scale` | `number` | Current D3 zoom scale factor (initially `1`) |
|
|
| `viewX` | `number` | Current D3 zoom translate X (initially `0`) |
|
|
| `viewY` | `number` | Current D3 zoom translate Y (initially `0`) |
|
|
| `graphWidth` | `number` | Map canvas width in SVG user units |
|
|
| `graphHeight` | `number` | Map canvas height in SVG user units |
|
|
| `svgWidth` | `number` | SVG element rendered width (px) |
|
|
| `svgHeight` | `number` | SVG element rendered height (px) |
|
|
| `pack` | `object` | Packed voronoi graph + all generated data |
|
|
| `grid` | `object` | Initial grid graph |
|
|
| `viewbox` | D3 selection | D3 selection of `#viewbox` `<g>` |
|
|
| `svg` | D3 selection | D3 selection of `#map` `<svg>` |
|
|
| `zoom` | D3 zoom behaviour | The active d3-zoom instance |
|
|
| `seed` | `string` | Current map seed |
|
|
| `options` | `object` | Global render/UI options |
|
|
|
|
### Rule for TypeScript/ES-module code in `src/`
|
|
|
|
All main.js globals are declared as ambient globals in `src/types/global.ts`.
|
|
Just **use them directly** — no `window.` prefix, no `(window as any)`, no `globalThis`.
|
|
TypeScript already knows their types.
|
|
|
|
```ts
|
|
// ✅ CORRECT — declared in src/types/global.ts, use as bare globals
|
|
buildCameraBounds(viewX, viewY, scale, graphWidth, graphHeight);
|
|
viewbox.on("zoom.webgl", handler);
|
|
|
|
// ❌ WRONG — unnecessary indirection
|
|
(window as any).scale(globalThis as any).viewX;
|
|
```
|
|
|
|
The only exception is a Node/test-env guard where the global may genuinely not exist:
|
|
|
|
```ts
|
|
if (typeof viewbox === "undefined") return; // guard for Node test env
|
|
viewbox.on("zoom.webgl", handler); // then use directly
|
|
```
|
|
|
|
In `webgl-layer-framework.ts` the `syncTransform()` method correctly reads:
|
|
|
|
```ts
|
|
buildCameraBounds(viewX, viewY, scale, graphWidth, graphHeight);
|
|
```
|
|
|
|
### Why this matters for new WebGL/canvas overlays
|
|
|
|
Any canvas or WebGL overlay that must stay pixel-aligned with the SVG viewbox **must**
|
|
read `scale`, `viewX`, `viewY` at render time — these are live globals updated on every
|
|
D3 zoom event. Do not cache them at module load time.
|
|
|
|
### Other public/modules globals of note
|
|
|
|
`toggleRelief`, `drawRelief`, `undrawRelief`, `rerenderReliefIcons`, `layerIsOn`,
|
|
`turnButtonOn`, `turnButtonOff`, `byId`, `tip`, `rn`, `P`, `gauss` — all utility
|
|
functions defined in public JS files and available globally.
|
|
|
|
## Module loading order
|
|
|
|
1. `public/libs/*.js` — third-party (d3, jQuery, etc.)
|
|
2. `src/utils/index.ts`, `src/modules/index.ts`, `src/renderers/index.ts` — ES modules
|
|
(bundled by Vite); these run **before** the deferred legacy scripts
|
|
3. `public/main.js` and `public/modules/**/*.js` — deferred plain scripts
|
|
|
|
**Implication:** ES modules in `src/` that call `WebGL2LayerFramework.register()` at
|
|
module load time are safe because the framework class is instantiated at the bottom of
|
|
`webgl-layer-framework.ts` (an ES module), which runs before the deferred `main.js`.
|
|
`main.js` then calls `WebGL2LayerFramework.init()` inside `generateMapOnLoad()`.
|