Filroden's FoundryVTT Modules

All modules respect your chosen light/dark theme and offer two colour options:

Changelog
Version 2.6.0

Version 2.6.0 lets you hand-push terrain past the normal 0% to 100% elevation range. Previously, raising sea level to shape nicely sized islands ate into how much room was left to draw mountains, since land elevation is always compressed into the space between sea level and 100%. Now the terrain brush, tectonic fault lines, and manual rivers can all push elevation beyond that range, so you can raise a taller peak or carve a deeper trench without needing to touch sea level at all. Procedurally generated terrain, the noise-driven hills and ridges the engine creates on its own, is not affected by this and still always generates within the normal range - only terrain you hand-edit afterwards can go further.

> Note: A few existing maps may look slightly different after this update. Convergent tectonic faults and hotspot island chains drawn at a high strength setting, in a spot where the noise happened to be favourable, could previously compute a peak taller than 100% and have it silently flattened to exactly 100%. That peak now shows its true, slightly taller height instead. This only affects maps with fault lines at or near maximum strength, and the difference is small (and more realistic).

FEATURES
- Unclamped edits: The terrain brush, tectonic fault lines, and manual rivers can now raise elevation above 100% or lower it below 0%, giving you room to hand-place a mountain taller than the current sea level's compression would otherwise allow, or a trench deeper than the ordinary seafloor, at any sea level. The on-canvas elevation readout shows the real value, so a hand-raised peak might read as, for example, 118%, and a hand-carved trench as -12%.
- Ocean now shades relative to the deepest point actually on the map, so a hand-carved trench reads visibly darker than ordinary ocean instead of looking the same as any other moderately deep water.
- Grid-cell exploration data: Exporting to a Scene now also writes a structured summary of every grid cell onto the Scene itself - its dominant biome, terrain, moisture and temperature, whether it has a river or borders the coast (and the name of any custom river you've drawn through it), and which of your regions, points of interest and routes touch it. This is aimed at other modules and game systems - for example, one that picks a random encounter when a token explores into a new cell - and has no effect on anything you see in Foundry yourself. No summary is exported for gridless maps.

IMPROVEMENTS
- Reduced the verbosity of the console logs when generating or updating maps.

BUG FIXES
- Dragging a Biome Rule Editor range handle, or picking an elevation zone preset, now stores the value rounded to the same two decimal places already shown on its chip. Previously the true stored value could differ from the display by a tiny fraction, so two ranges dragged to what looked like the same boundary (for example, both reading "0.55") could actually leave an imperceptibly thin, unintended gap between them that no rule covered. This only affects ranges set from this point on; a rule range saved before this update keeps its exact old value, so an existing gap of this kind needs that range re-dragged (even nudged and back) or reset via the elevation zone presets to close it.

UNDER THE HOOD
- BrushEngine#stampTerrain no longer clamps elevation to [0, 1]; every terrain tool, and the slope tools' anchored target elevation, can now write and track values outside that range. Live painting and BrushLayerCache replay continue to share this exact code path, so both stay in lockstep automatically.
- TectonicEngine's convergent, divergent, and hotspot-chain formulas now clamp their internal damping factor rather than their output. Previously, feeding one of these faults elevation already outside [0, 1] would make the damping factor negative and reverse the fault's direction entirely (a convergent fault would lower an already-tall peak); clamping the factor instead makes the fault simply stop adding further effect once terrain is already at or past the old boundary. Numerically identical to the previous formula for any elevation that was already within the old range.
- HydrologyEngine#carveRiverCrossSection now writes the same unclamped value it compares against when deciding whether to carve, instead of comparing against the true value but writing a floor-clamped one. This closes a latent ordering bug: a river carved through hand-lowered terrain can now deepen it below the old floor, rather than the write being silently floored back to 0 and raising the terrain it was meant to deepen.
- ProceduralOrchestrator.planRepaint now tracks the map's lowest elevation (cachedMinElevation) alongside its highest, in the same single scan, and forces a full canvas repaint if either one moves.
- ProceduralEngine#paintOceanPixel shades ocean depth relative to the discovered lowest point instead of a fixed floor of 0, using the same pattern the land shader already used for its highest point. Identical output to before on every map with no negative elevation.
- BiomeRuleEngine's existing open-boundary rule matching, where a custom biome rule resting on a literal 0 or 1 edge already matches any value beyond that edge, turns out to be exactly the mechanism elevation overflow needs, with no change required. Documented in place so it isn't tightened later by someone who doesn't realise what now depends on it.
- New GridDataExporter computes the grid-cell export data once per Scene export, from the map's own generated buffers and the exact same ProceduralEngine.resolveBiomeLookup priority chain the live biome layer and on-canvas hover readout already use, so the exported biome can never disagree with what's rendered on the map. Terrain bands are defined by a lower elevation threshold only, open-ended at the top, matching this version's own move away from a clamped elevation ceiling.
- New GridAggregator provides the point-in-polygon, majority-vote and segment-intersection primitives the per-cell aggregation is built from, independent of any particular grid shape - a future Voronoi-mesh content layer can reuse it for its own cell rasterisation.
- New FILRODENSWMB.GRID_DATA config block holds the grid-cell export's band thresholds and schema version; new FILRODENSWMB.GRID_TYPES centralises Foundry's grid-type constants, now shared between SceneExporter and GridDataExporter instead of being defined twice.

Version 2.5.0

Version 2.5.0 makes editing large maps much faster. Until now, nearly every edit on a map with brush strokes, fault lines or custom rivers ended in something close to a full regeneration, however small the edit, and the wait grew with every stroke on the map. Now only the part of the map that changed is recalculated and redrawn, and the result is the same as regenerating the whole map.

These times were measured in Foundry on a 3210 x 2400 map with 7,158 brush strokes and 46 custom rivers. They are the processing times, and do not include the 2 second pause between finishing a stroke or moving a node and the change being applied, which has not changed.
- Finishing a brush stroke: from over 6 seconds to about 0.2 seconds.
- Undoing or redoing a brush stroke: from about 6 seconds, spread over two steps, to about 0.2 seconds in one.
- Moving a custom river node, and undoing it: from 7.4 and 6.7 seconds to 0.22 and 0.24 seconds.
- Loading a map, and changing the seed or a slider: these still regenerate the whole map, but replaying the brush strokes, the largest part of that on a map with many strokes, is about four times faster. On this map the replay takes 3.6 seconds.
- Painting with the brush: each map layer now sends only the rows that changed to the graphics card instead of the whole layer, which helps most on large maps.

> Note: A few small changes to existing maps may occur. Procedural rivers, the ones traced from spring pins rather than drawn by you, are now each traced independently of the others, so where the terrain left a river a choice between equally low neighbouring pixels it may take a slightly different route. Any difference is small and was not visible when comparing maps by eye.

IMPROVEMENTS
- Land masks can now be renamed, and switched between land and ocean, using the new Edit button in the Land Masks list or by double-clicking one of the mask's nodes.
- Each entry in the Land Masks list now has a green line for land or a red line for ocean, so you can tell them apart once they have been renamed.
- A region or land mask that you stop drawing before it has three nodes is now discarded, rather than being left in its list as a shape that cannot be edited or completed. Undo and Redo still work as normal, so a shape shortened by Undo can still be brought back with Redo.
- The Undo and Redo highlight for a land mask change now says "Land Mask" instead of the generic "Vector Edit".
- Guided mode's Scene toolbar now has the same pause toggle and Apply Changes button as the Features toolbar, so you can insert and drag land mask nodes without waiting for the terrain to regenerate after each one.
- Changing tool or finishing an edit session now always turns automatic terrain generation back on. Previously it stayed paused, so the next tool you opened could start out paused without you noticing.
- Finishing a brush stroke on a map with faults or manual rivers, and undoing or redoing a brush stroke, no longer replays the map's whole brush history, and now refreshes only the part of the map that changed instead of recalculating the climate and repainting the whole map. The result is the same as a whole-map refresh.
- Adding, moving or deleting a fault line or manual river, or its nodes, changing a fault's strength, and undoing or redoing any of these, no longer regenerate the whole map. Only the part of the map that changed is recalculated and repainted, and the result is the same as a full regeneration. Changing a setting such as the seed, sea level or a climate slider, and editing a Guided mode land mask, still regenerate the whole map.
- Replaying a map's brush strokes, which happens when a map loads and whenever a full regeneration is needed, is about four times faster. The terrain it produces is unchanged.
- Redrawing part of the map after an edit, whether a brush stroke while you paint, undoing or redoing one, or moving a fault or river node, now updates only the rows of each map layer's image that changed, instead of copying and re-uploading the whole image every time.
- Keeping edits quick uses extra memory: on a map of this size about 38 MB for a copy of the brushed terrain, up to 64 MB for undo data, and a 31 MB working copy that is released after 30 seconds without an edit. If the browser cannot supply the memory, the module falls back to the slower method instead of failing.

BUG FIXES
- Undoing or redoing a change to a Guided mode land mask (such as moving or adding a node) now regenerates the terrain to match. Previously the mask shape moved but the terrain stayed as it was until something else triggered a redraw.
- Each node you place while drawing a land mask is now its own Undo step, the same as when drawing regions, routes, and fault lines. Previously Undo skipped over them and stepped back to an earlier, unrelated change, which could remove several shapes at once or bring back a mask you had deleted.
- Switching tool, or entering 3D view, while a land mask is still being drawn now completes the mask and regenerates the terrain. Previously the terrain was left out of date until something else triggered a redraw.
- Clicking or double-clicking a node, pin, label, or decoration without dragging it no longer counts as an edit. Previously it added an empty Undo step and, for land masks, fault lines, and custom rivers, triggered a terrain regeneration. The pointer now has to move a few pixels before an item starts to drag.
- Undo, Redo, and deleting a fault line or manual river from its list now respect the paused state instead of regenerating the terrain straight away. Apply Changes also no longer stays lit after a regeneration has already picked the changes up.
- Entering 3D view while automatic generation is paused now applies the pending changes first, so the 3D scene matches the map.
- Editing a river, a fault line, or a river source pin no longer changes the route of unrelated rivers elsewhere on the map. Previously every procedural river drew from one shared sequence of random choices, so a change that altered the length of one river gave every river traced after it different choices, and about a third of the map's rivers could be redrawn along different routes.

UNDER THE HOOD
A fuller account of how these changes work, and how they were tested, is in the technical write-up in the repository's Discussions.
- BrushEngine: the stamp loop was rewritten, with output bit-for-bit identical to before. Stroke settings are resolved once per stamp, each row only visits the pixels that can lie inside the brush circle, and distances use exactHypot, an inline copy of V8's two-argument Math.hypot.
- BrushLayerCache: the brush engine keeps a second copy of the terrain with every brush stroke applied, updated as strokes are finished, undone and redone, so a rebuild copies it instead of replaying the history. It falls back to a full replay whenever it cannot be trusted or its memory cannot be allocated.
- ProceduralOrchestrator.rebuildChangedTerrain and BufferDiff: a rebuild is built off to the side and compared bit for bit with the working terrain, so the climate, river and repaint stages run only over what differs. A repaint whose highest point moved covers the whole map, because land shading depends on it.
- ProceduralOrchestrator.canSkipBaseRegeneration: compares a description of everything the base terrain depends on (describeGenerationInputs) with the one recorded after the last full generation, and skips regenerating the base terrain when only strokes, faults, rivers or pins changed.
- RegionUploadResource: a subclass of PIXI 7's BufferResource that copies and uploads only the changed rows of a layer, and sends the whole texture whenever it cannot be sure the GPU copy matches. It is written against PIXI 7.
- ProceduralEngine.generateRivers: each river now draws its random choices from a stream of its own (riverTracePrng), seeded from the map seed and the pixel index of its spring, instead of one stream shared by every river. Editing one river no longer shifts the choices of the rivers traced after it.
- RenderTimer: full renders, refreshes, undo and redo each finish with one console summary of every phase's time and share of the total, including the canvas repaint, which the individual phase logs did not cover.

Version 2.4.0

FEATURES
- Added an Erase Biome brush next to the Paint Biome tool, so you can clear a hand-painted or Pack Ice biome override back to its normally calculated biome without having to repaint over it with something else.

IMPROVEMENTS
- Coastlines generated in Guided mode now look far more natural, with real inlets, bays, and small islands, instead of closely tracing the shape of the polygon you drew. This is most noticeable on complex, many-node shapes, which previously came out blocky. The Coastline Fracture setting now actually reshapes the coastline itself, rather than only bending a line that still followed your drawn edge. If you have existing maps built with Guided mode, particularly with a high Coastline Fracture value, regenerating their terrain under this update will look noticeably different - it's worth reviewing that setting (and lowering it if the result looks too broken up) before regenerating an existing map.
- Added a "Delete All Land Masks" button to the Scene tool in Guided mode, beneath the Land Masks list, so you can clear every drawn land mask in one action instead of deleting them one at a time.
- The Undo and Redo buttons now show how many steps are available in their tooltip (e.g. "Undo (4)"), and are disabled whenever there's nothing left to undo or redo.

BUG FIXES
- Guided mode's land mask editing shapes no longer appear in exported Scene PNGs (player or GM view) if they were left visible from the Scene tool.
- Loading a map with a lot of hand-painted terrain or biome history no longer inflates the Undo/Redo step count to match its entire paint history. Loading a map now always starts a clean undo session, the same way it already did for pins, routes, regions, and other drawn features.
- Switching between Add Land and Remove Land while editing guided-mode land masks now finishes the shape you were drawing first, the same way switching modes already does for other tools. Previously, switching mode kept adding to the shape you'd already started instead of beginning a new one.

UNDER THE HOOD
- ProceduralEngine#applyGuidedDetail no longer suppresses coastal detail noise to zero exactly at the drawn boundary. A new #computeEffectiveCoastDistance helper perturbs the guided-mode distance field with independent, tapered noise instead, fading to zero over a band either side of the boundary (configured via the new FILRODENSWMB.GENERATION.COASTAL_VARIANCE block, expressed as ratios of CONTINENT_SCALE) so land/ocean ownership - and the coastal shelving maths that depends on it - remains guaranteed correct in the far field. The guided-mode distance field is now also sampled with bilinear (sub-pixel) precision rather than snapped to the nearest whole pixel. #bilinearSample was generalised to accept width and height separately, since it previously assumed a square mesh.

Version 2.3.0

FEATURES
- Custom Biome Management: Custom biomes can now be renamed and given an optional code (for example, to match a terrain code from your game system) after creation, instead of only being deletable. They're also now managed in their own Custom Biomes list in the Style Library, matching how Route, Region, and Label Quick Styles already work.
- Custom Biome Auto-Generation Rules: Custom biomes can now be given their own auto-generation rules - ranges of elevation, moisture and temperature that, when matched, tell the procedural generator to use that biome automatically. Open the new Biome Rule Editor from the Biomes tool to set them up. Built-in default biomes always remain as a guaranteed fallback for anywhere your rules don't cover, so a map is never left with unassigned biomes.
- Added a "Preview Rule Coverage" button next to the Biome Rule Editor button. Hover it to highlight every area of the current map that's using a default biome rather than one of your own rules, making it easy to spot gaps in your rule coverage.
- Custom biomes can now be set to render as a solid colour over water, just like Pack Ice, instead of always appearing transparent below sea level.

IMPROVEMENTS
- Added a colour swatch inside the biome toolbar dropdown, making it easier to choose which biome you want to paint on the map.
- Increased the default width of the tool sidepanel to provide more space.
- The Custom Biomes list now shows an icon against any biome that has auto-generation rules attached.
- Importing a Style Library settings file that includes custom biome rules updates the map immediately.

BUG FIXES
- Fixed an issue where undo would not remove custom biomes painted on the map.
- Fixed the height and spacing on the new export/import settings buttons.
- Fixed an issue where deleting a custom biome that had been painted onto the map, then undoing and redoing that deletion, could turn the painted area solid black.
- The on-canvas info bar's biome reading now reflects hand-painted and rule-generated biomes, rather than always showing the default calculated biome.
- Deleting a custom biome now correctly marks the map as needing to be saved.

UNDER THE HOOD
- Consolidated colour format change methods into their own class, ColorMath.
- Added a helper to generate random IDs.
- Added BiomeRuleEngine, a dedicated module that compiles custom biome rules into flat lookup tables for fast per-pixel matching during generation.
- Consolidated biome colour resolution (painted overrides, custom rules, and built-in defaults) into a single shared function, used by both the map renderer and the on-canvas info bar.
- Custom biome IDs are now issued from an ever-increasing counter rather than one derived from the current list's highest ID, preventing a deleted biome's ID from being silently reused by an unrelated new biome.

Version 2.2.0

FEATURES
- Custom Infrastructure Pins: Introduced two new settings to disable built-in infratructure pin icons, and register your own. Icons must be SVG format and be solid white on transparent backgrounds.
- Region Quick Styles: You can now add, edit, or delete custom Quick Styles for regions in the Settings, matching the existing options for routes and labels. Updating a Quick Style applies the changes to every region using it. Deleting a Quick Style converts affected regions to a custom configuration to preserve their appearance.
- Mass Edit: Points of interest, routes, regions, and custom labels can now be batch-edited. Enable Select in a panel's header, tick the items you want to change, then use Mass Edit to apply visual changes to all of them at once, including assigning a Quick Style and, for points of interest, routes, and regions, the styling of their attached label. Only the properties you tick are changed; everything else is left as it was.
- Save Styles: Custom biomes and quick styles (routes, regions or labels) can all be exported and imported allowing you to use them on other maps or share them with other users.

IMPROVEMENTS
- Split the existing Settings tool into two. The new Settings tool focuses on map default values, and the new Style Library tool focuses on styles and the new Save Styles tool.
- Route, Region, and Label Quick Styles in the Style Library now show how many features on the current map are using each style, so you can tell at a glance whether one is safe to delete.

BUG FIXES
- The saved journal page now shows which terrain generation engine created the map (Standard, Flat, Advanced, or Guided), along with that engine's own settings. This was a visual bug only. This fix only affects maps saved after this update; existing saves pick up the new summary the next time you save them.
- Biomes painted with the Biome brush, other than the two water biomes or Pack Ice, were not surviving a map being reopened, silently reverting to whatever biome the automatic terrain calculation produced for that tile instead. Custom biomes were affected too. Your original brush strokes were never actually lost, so affected maps will show their correct painted biomes again as soon as they're reopened.

UNDER THE HOOD
- Regions saved before this update are marked as not using a Quick Style on load, so their existing appearance is left untouched rather than being attached to a preset.
- Fixed a missing argument in ProceduralOrchestrator.rebuildFromHistory's call into BrushEngine.replayHistory, which caused the active rebuild bounds to be passed into the seaLevel parameter instead, corrupting the land/water check used by biome-layer strokes during replay. Also restored the active bounds parameter that was never being forwarded into the per-stroke stamping loop, laying the groundwork for future bounded/partial history replay work.

Version 2.1.0

FEATURES
- Terrain Generation Engines: Introduced a dropdown to select between four terrain generation engines: Standard, Flat, Advanced and Guided. Legacy maps default to Standard to preserve existing saves.
- Standard Terrain Engine: This was the only method available before this update. The Standard generator creates an infinite surface and shows a small window as the base map, meaning you can pan and zoom to discover new terrain not visible initially.
- Advanced Terrain Engine (Tectonic): Generates a fixed-size map, meaning infinite pan and zoom controls are disabled. It first calculates where land can occur and forces all other areas to be deep ocean to create highly natural continents. It then generates tectonic plates to define distinct landmasses and simulates how plate collisions distort the landscape, before layering on a detailed terrain model. All of these steps can be fine-tuned by the user after the initial map is generated.
- Guided Terrain Engine (Tectonic): Generates procedural terrain using a similar model as Advanced mode inside polygons drawn by the user.
- Flat Terrain Engine: Generates a flat, sea-level landmass with no initial procedural rivers. Designed as a blank slate for manual brush sculpting.

UNDER THE HOOD
- Implemented a ProceduralOrchestrator to decouple terrain, climate, and feature generation logic from the main application controller.
- Added a buffer around the canvas where vector nodes can be dropped to allow lines and regions to be drawn outside the visible boundary of the canvas.
- Added a mask to hide anything drawn in the buffer area unless edit mode is active.
- Defined more magic numbers in config.js.

Version 2.0.0

BREAKING CHANGES
Fixed an issue where orographic lift (rain shadows) was not being calculated using modified terrain and applied a fixed distance regardless of map resolution or scale. Procedurally generated biomes will look different on existing maps that have had their terrain modified (via the terrain brush, custom rivers, or tectonic faults).

Maps with minimal terrain changes will see minor differences, while maps with hand-drawn mountain ranges will see more accurate rain shadows.

Additionally, regional maps will now properly scale their climate patterns to ensure biomes remain visually consistent with their parent world maps.

FEATURES
- Targeted Terrain and Biome Updating: Only the area around a terrain or biome edit will be updated procedurally, leaving the rest of the map unchanged. This reduces the time taken to recalculate terrain and biomes when using the terrain or biome brush tools, or when adding custom rivers or tectonic faults. Loading the map will still require a full regeneration, but subsequent edits should feel faster.
- Quick Styles for Labels: You can add, edit, or delete custom Quick Styles in the Settings. Updating a Quick Style applies the changes to every label using it. Deleting a Quick Style converts affected labels to a custom configuration to preserve their appearance.
- Undo/Redo Highlighting: Hovering over the undo or redo button will show which area of the map and what type of feature will be changed if you press it. The Undo/Redo buttons have been moved to the top right of the canvas where they are always visible, even when not in edit mode. You can also use the standard Undo/Redo keyboard shortcuts (for Windows undo is Ctrl + Z and redo is Ctrl + Y or Ctrl + Shift + Z).
- New Mouse Action: Double-Click: Double-clicking any interactable feature on the map (infrastructure pins, route and region nodes, etc.) opens its edit dialogue.
- Global Undo/Redo History: A unified undo/redo history now steps through all changes in order, regardless of the active tool. Previously, raster edits (terrain, biomes) and vector edits (pins, routes, labels) used independent histories.
- Toggle Live Terrain Generation: Added a button to the edit toolbar for the Feature tool to toggle live terrain generation. When disabled, a second button allows pending terrain changes to be applied manually. This makes drawing river or fault lines easier.

IMPROVEMENTS
- Features that automatically generate labels now include label properties within their main edit dialogue.
- Labels now support a maximum width (0 for unlimited), which enables word wrapping. Text justification (left, centre, or right) is also supported.
- Colour pickers with pre-defined palettes now use a standard dropdown for swatches, alongside an "Other..." button for custom colours.
- Added new icons for infrastructure pins.
- The Edit Pin dialogue now displays a visual grid of pin icons instead of a text list.
- The UI now locks and displays an in-progress indicator while generating terrain, biomes, or managing files.
- Reduced grid line opacity.
- Journal map pins created during the export scene process will now be scaled between 32px (Foundry's minimum) and 96px depending on the map's resolution.
- Lower resolution exported maps (PNG or scene) are now dynamically over-sampled to make labels and icons sharper. Oversampling is scaled between 2x and 1x, depending on the map width.
- The moisture scale slider is no longer infintely precise! It will now only show values in steps of 10.

BUG FIXES
- Fixed an issue where infrastructure icons were not being included in maps during the scene export process.
- Fixed an issue where the map would not work when the module was detached from Foundry and the window was maximised.
- Fixed an issue when the module was detatched from Foundry. A map would stall while it generated topography and it would not move on to the next stage of the generation process unless the window was reattached to the Foundry window.
- Changing climate, terrain, grid, or biome colours now correctly marks the map as modified, prompting a save warning before closing or loading a new map.
- Grid visibility state now saves correctly with the map.
- Fixed an issue where legacy routes from earlier versions were missing style properties.
- Fixed an issue where switching between the terrain and climate tools would not reset the active brush tool.
- Fixed an issue where discarding changes on a map and reloading the same map still showed those changes. This was an issue with the cache and did not affect the saved map.
- Fixed an issue where the grid for a loaded map would use the map dimensions from the previous map (if different).

UNDER THE HOOD
- MapStudioApp Refactor: Extracted hard-coded constants to FILRODENSWMB. Refactored MapStudioApp into a strict UI manager, introducing new classes for spatial maths, state management, dialogue management, and regional map generation. Most UI elements are entirely driven by the data model, reducing the need to directly manipulate the DOM. Some DOM manipulation is retained for map controls and undo/redo buttons to avoid re-rendering the map canvas and destroying the PIXI container.
- StudioCanvas Refactor: Separated terrain features (river source pins, procedural rivers, custom rivers, and fault lines) into dedicated graphics layers.
- Performance Improvement: Orographic Lift Resampling Climate engine updated to read the elevationData array rather then recalculate it a second time for each pixel.
- Performance Improvement: Boundary Sorting in Basin Filling Added a MinHeap (priority queue) to improve generation of lakes.
- Performance Improvement: String-Keyed Sets in Hydrology Replace the use of string literals with a generation-stamped Uint32Array, reducing the memory footprint of river tracing.

Version 1.2.0

FEATURES
- Custom Rivers: Added a line tool to the Features tab to draw custom rivers. The engine places a river source at the highest point of the drawn line and carves a continuous downhill channel. The tool will cut gorges through any higher terrain in its path and drop to form waterfalls over cliffs.

IMPROVEMENTS
- Regional maps can now be cloned as new standalone master maps, rather than solely as regional children of another map.
- Using Ctrl + Left Click will now let you delete an infrastructure pin.
- Deleting custom rivers, faults, infrastructure pins, routes, region layers, labels and decorations now require a confirmation.
- Removed nodes snapping to infrastructure pins, allowing precise placement of lines and regions.
- Vector node sizes remain fixed when zooming the canvas.
- Nodes can now be placed closer together.
- Left-clicking near a node while drawing a vector line no longer ends the line. Only right-clicking will end the line (except regions where clicking the starting node will close the polygon).
- Scrolling lists now remember their position.
- Zooming to a feature also now pulses a bounding box around it to help you spot it on the map.
- Labels for new routes will now default to font size 0.5 and be set to hidden. Both can be changed in the Label tool.
- The list of tectonic faults will now be sorted alphabetically in the Terrain Features tool.

BUG FIXES
- Fixed custom biomes and quick styles not being re-added to the UI when loading a map.
- Fixed custom biomes not being reapplied to an area when its elevation has been changed using a terrain brush.
- Fixed an issue where tectonic fault lines would not reset when creating a new map.
- Tectonic fault lines will now be included when creating regional maps.

UNDER THE HOOD
- Hydrology Engine: Implemented a monotonic downhill carve algorithm to process custom river routes. The engine evaluates the drawn spline sequentially and mathematically enforces a continuous downward gradient. This ensures the river slices cleanly through mountains and drops into valleys without accidentally raising the surrounding terrain to form aqueducts. A quadratic falloff is then applied to blend the newly carved riverbanks seamlessly into the existing topography.
- Vector Architecture: Refactored the spatial node lifecycle (insertion, deletion, and termination) for all linear tools into a unified, data-driven registry pattern. This consolidates the interaction mathematics for rivers, faults, and routes into a single generic handler, removing repetitive conditional branches.
- Parameter Configuration: Consolidated the procedural engine's parameter generation into a single derived method, eliminating duplicate configuration logic and preventing architectural drift between local UI state updates and regional map extraction.
- Entity Deletion Lifecycle: Expanded the data-driven registry pattern to manage entity deletions. Seven distinct deletion methods have been unified into a single generic handler.

Version 1.1.0

FEATURES
- Tectonic Fault Lines: Added a line tool to the Features tab to simulate plate tectonics (convergent, divergent, slip, and hotspot chains). This provides a method to draw mountain ranges, ocean ridges, or island chains directly.
- Custom Quick Styles for Routes: You can add, edit, or delete custom Quick Styles in the Settings tool. Updating a style applies the changes to every route using it. Deleting a style converts affected routes to a custom configuration to preserve their appearance. Pre-configured styles have been removed.
- Coloured Infrastructure Pins: Infrastructure pins can now be tinted with custom colours.

IMPROVEMENTS
- Right-clicking the canvas now ends an active route, fault line, or region polygon.
- Active lines and regions display in a distinct colour while being edited. The current last node is also larger while active.
- Infrastructure pin sizes can be configured in the edit toolbar. The initial label font size automatically matches this scale.
- Added a black border to all routes to improve visual contrast against the terrain.
- Region opacity is now a global display setting managed in the Settings toolbar.

BUG FIXES
- The first node of a new infrastructure route now displays immediately when clicked.
- Changing the sea level now triggers a full topography recalculation to accurately preserve coastlines and continental shelves.
- Infrastructure tooltips are disabled in any edit mode to prevent "ghost" tooltips appearing.

UNDER THE HOOD
- Isolated the procedural generation PRNG streams to prevent river and lake desynchronisation when feature settings are changed.
- Limited the undo history to the last 40 actions to prevent memory issues.
- Improved garbage collection to prevent memory issues.

Version 1.0.0

SAVED MAP CHANGES
The procedural noise generators and vector elevation brushes have been normalised. If you load a map created in an earlier version, you will notice peaks and valleys look more organic and less like flat plateaus. You may also see slight shifts in coastlines and biome placements. These shifts are minor but ensure vastly improved terrain generation moving forward.

FEATURES
- Regional Map Creation: Generate a new, high-resolution map from a cropped area of your world. All terrain edits and vector features are preserved, and the new maps are nested as children under their parent map in the map manager.
- Themes: Added light and dark themes, alongside a new configuration toggle to switch the base interface colour between gold and teal.
- Custom Biomes: Create custom biomes in the Map Configuration tool, which then appear as selectable brushes in the Biome tool.
- Level Terrain Brush: Added a new terrain brush that levels terrain to match the elevation at the centre of your click. The feather setting controls how smoothly this blends into the surrounding area.

IMPROVEMENTS
- Procedurally spawned river sources are converted into map pins so they can be moved or deleted.
- When creating a new map with a resolution other than the default 1000 x 1000 pixels, the noise scale used by the procedural generator is adjusted to reflect the new resolution. This does not affect existing maps.
- Icons for infrastructure points of interest are now white by default. This is to allow them to be coloured in a later update.
- UI lists (such as regions and saved maps) are now sorted alphabetically.
- Route quick styles now function as toggles. Clicking an active style resets the route to its default settings.
- The biome brush now paints solid areas rather than scattered pixels, ensuring painted biomes better match the visual style of the generated map.
- Adjusted the temperature model to produce smooth, map-wide climate variations rather than scattered noise. Note: Maps generated during the beta phase will experience a slight shift in biome placement when loaded in this version.
- Added a brief pause when typing inputs or dragging sliders so you can finish your adjustment before the map redraws.

BUG FIXES
- Fixed an issue where the "Remove Pin" button failed to operate while editing within the Features tool.
- The Grid Type select dropdown will now correctly show the active pattern when loading a map.
- Switching away from the Biome tool will now return the biome layer to its inactive opacity, allowing contours and terrain to be seen.

UNDER THE HOOD
- Biome Brush Performance: Isolated the biome brush rendering pipeline so it no longer triggers a recalculation of the procedural climate models, significantly improving brushing performance.

Version 1.0.0-beta1

FEATURES
- Export to Scene: Maps can now be exported directly to a playable scene. The base map contains player-visible information, while GM-only data is saved to a hidden map tile. The tool also generates a journal containing region and feature descriptions, and creates map pins linked directly to these journal pages.
- Labels: A new label tool displays names for points of interest, routes, and regions. In edit mode, labels can be dragged or rotated (using the scroll wheel). Left-clicking adds a custom label, and CTRL/CMD + left-click removes it. Labels from other tools can be hidden but not deleted. Text outlines automatically adapt to the background colour for readability.
- Cartography Decorations: Scale bars, borders, and custom images can be added to the map. In edit mode, these can be dragged, rotated with the scroll wheel, and resized using SHIFT + scroll wheel.
- Slope Brushes: Two new terrain brushes allow for gradual sloping. The strength setting controls the gradient, and feathering controls the blend with surrounding terrain.
- Global Scaling: Moving or scaling the terrain now automatically updates the position and scale of all vector layers (features, infrastructure, regions, and labels) to maintain alignment.

IMPROVEMENTS
- Feature visibility now uses a three-state system: Player, GM, or None.
- Added map controls to toggle the display of features based on their visibility state.
- The mouse cursor updates to show the brush area when using terrain or biome tools in edit mode.
- Reduced the minimum brush size to 2px for finer detailing.
- The application now prompts to save or discard unsaved changes before closing or loading a different map.
- Renamed the "Scene" tool to "Create New Map" and moved the map seed input into this section.
- The brush size tool now applies when placing or blocking river springs. River sources and blocked springs can be dragged or removed just like standard pins.
- Added UI warnings if the terrain scale is set above or below the generator's limits.
- Moved the grid layer to render beneath labels and cartography decorations.
- Infrastructure icons can now be resized.
- Performance Updates: The UI refreshes significantly faster when using vector tools, as the full map only recalculates when pixel layers are modified. Maps also now only calculate once on loading.

BUG FIXES
- Moving or scaling the map after using the terrain brush correctly reapplies the brush strokes at the new coordinates.
- Changing the map seed reliably generates a new map.
- Creating a new map resets the quick save state, preventing accidental overwrites.

UNDER THE HOOD
- Consolidated UI action handlers across multiple tools.

Version 1.0.0-alpha4

Note: The icon for "Export to PNG" has been changed to a "PNG" icon and the "Image" icon is now used for the new "Reference Image" tool.

FEATURES
- Regions: Added the Regions tool to draw, edit, and organise custom polygons. Regions are grouped into layers and feature customisable fill colours, patterns, line styles, border thicknesses, and geometric smoothing.
- Reference Image: Added a new tool to load a reference image. Once loaded the mouse Left Click can be used to drag the image into position and SHIFT + Scroll Wheel can be used to scale it. Scale and offset buttons are available in the Reference sidebar for fine tuning. The image can be toggled on and off using the map tools in the bottom right of the canvas. The reference image will be automatically excluded from any exports.

IMPROVEMENTS
- Sorted the display of routes by their line thickness, so wider roads appear on top.
- Changed the end cap style of route lines to be rounded, not square.
- Include the map name in the "Quick Save" button tooltip if one is set.

BUG FIXES
- Fixed over-aggressive memory optimisations that were preventing the terrain smooth brush being recorded and replayed correctly when a map was saved and reloaded. This does mean that saves made in previous alpha versions that included edits using the smooth brush may not look as intended when reloaded.

Version 1.0.0-alpha3

FEATURES
- Add Infrastructure: Added the Infrastructure tool to add and edit points of interest (icons) and routes (lines).
- Move Infrastructure: Points of Interest can be dragged to reposition them when edit mode is enabled. Route nodes can also be dragged. New nodes can be added by using SHIFT + left-click and removed by using CTRL (or CMD) + left-click.

IMPROVEMENTS
- Prevented vector features (like river sources or the new infrastructure items) being added outside the map boundary.

Version 1.0.0-alpha2

FEATURES
- Export to PNG: Maps can now be exported as a full resolution PNG from the main toolbar. This is a temporary feature until more extensive export features are added.

IMPROVEMENTS
- Entering 3D View now hides all tool sidebars.
- Changing tools while Edit mode is active will now disable the edit mode.

BUG FIXES
- Fixed an issue where performing a Quick Save would not visually update the map summary in the journal entry due to a missing embedded document ID. This did not affect the actual saved map data.

UNDER THE HOOD
- Added persistent sprite caching to the 2D canvas to stop memory spikes and frame drops when using the brush tools.
- Refactored the core procedural engine to utilise array buffer pooling. This prevents memory leaks and significantly reduces garbage collection stutters when rapidly painting complex terrain.
- The brushed layer, the scratch buffer used to find what changed (about 31 MB on a 3210 x 2400 map), and the undo tiles are extra memory on top of the map's own buffers, so each now has a guard for machines that run short. If the browser refuses to allocate the layer, rebuilds replay the brush history straight into the working terrain as they did before the layer existed. If it refuses the scratch buffer, refreshes cover the whole map instead of just the changed area. Either way the result is identical and only the speed suffers, a warning is written to the console, and another attempt is made at the next full generation. Running out of memory while saving a stroke's undo tiles also falls back to a full replay, while any other error still surfaces. The scratch buffer is released after 30 seconds without a refresh and when the window closes, and the undo tile budget shrinks on maps above about 22 million pixels (never below 8 MB) so that the layer, scratch buffer and tiles together stay near 256 MB. In randomised testing with each allocation made to fail (always, one at a time, and at random), every layer was still bit-for-bit identical to a whole-map refresh.

Version 1.0.0-alpha1

Initial Alpha Release A preview release to see the physical geography creation and editing tools.

Filroden's World Map Builder

Latest Version Foundry Version License System Agnostic RTL Support Download Count Download Count Last Commit Issues

Welcome to Filroden's World Map Builder

Filroden's World Map Builder is a system-agnostic cartography tool. It generates terrain, moisture and temperatures using a procedural, deterministic model so using the same "seed" will generate the same model. It then calculates appropriate biomes taking into account the latitude and underlying models including wind patterns. You can scale and offset the result to frame a map that is close to your idea so that you can apply the final edits to the world using non-destructive vector brushes, then place terrain features, infrastructure, regions, etc.

Maps are saved in Journals and stored in a Journal Compendium. The procedural plus non-destructive brush approach means the resulting saved journal is very compact in size.

Module Interface

Main Features

  • Advanced Procedural Generation: The underlying engine calculates authentic topography using layered noise and geological stretch parameters. It dynamically simulates climate by mapping global temperature gradients and tracking geographical orographic lift (rain shadows) to accurately determine Whittaker biomes.
  • Custom Biome Auto-Generation: Define your own biomes and give them auto-generation rules - ranges of elevation, moisture and temperature - so they appear automatically wherever the procedural generator produces a matching climate, with the built-in defaults always available as a guaranteed fallback. A hover preview shows exactly where a map is still relying on those defaults, so gaps in your rule coverage are easy to spot.
  • Four procedural terrain models: Choose from standard, flat, advanced (tectonic) or guided procedural terrain models. Each provide different benefits.
  • Dynamic Hydrology Systems: Rivers are carved procedurally using greedy downhill algorithms, naturally pooling into lakes until they overflow their basins, and freezing intelligently based on altitude and regional climate thresholds. Additional river sources can be placed manually, and procedurally generated sources can be removed.
  • Non-Destructive Vector Brush Engine: Edit the terrain (raising, lowering, and smoothing) or paint custom biomes with a responsive freehand brush tool. Under the hood, edits are saved as a spatial vector history rather than static pixels, preserving your exact strokes for future map scaling and regional zooming.
  • Vector Information Layers: You can add infrastructure (points of interest, routes, etc), regional polygons, labels and cartographic decorations to any map, fine-tuning their placement, size and style.
  • Easy Regional Map Creation: Once your master world map is created you can generate regional maps that faithfully match the original but at much higher resolution. Because of procedural generation, this provides almost infinite ability to "zoom in" and create larger and larger scale maps (from World to almost street level). There are limits, so the more you increase map scale, the flatter the map will become.
  • Export to Scene: All features (and entire layers) can be set to be visible to players, GMs or no-one. When you export the map to create a new Foundry Scene, it will export the player visible elements to the background image and place a map tile over it containing the GM-only features. A Scene Journal is also created which contains any feature names and descriptions and each feature is linked from the map to the journal using map pins.
  • Export to PNG: If you want to save the map for external use, you can also export the current visible features to a PNG file.
  • Interactive 3D Visualisation: View your 2D cartography in an interactive 3D web view. The biome map is draped over your custom topography, complete with topographical river vectors, ocean planes, and dynamic lighting. This feature is purely visual and included for fun. It will not update to any changes made until it is toggled again.
  • Compendium Integration: Maps are saved directly to a dedicated compendium. Each save automatically generates a readable journal showing your parameters. The application UI contains map management tools which let you to load, duplicate, rename, or export your worlds as shareable JSON files.

Example Maps

The following are two examples of maps I created in the module together with links to their JSON files which can be imported into the module.

World Map (generated at 4000 x 4000 pixels)

World map

Link to map JSON file: https://github.com/Filroden/Filrodens-world-map-builder/samples/fwmb_aethoria.json (36 KB)

Regional Map created from the above World Map (generated at 4000 x 2730 pixels)

Regional Map generated from the World map

Link to map JSON file: https://github.com/Filroden/Filrodens-world-map-builder/samples/fwmb_eldoria.json (32 KB)


How to Open the Module

Filroden's World Map Builder can be opened from the Scenes sidebar. A new button has been added at the top of the sidebar called Map Builder.

Please see the Wiki for more details on how to use the module.

Roadmap

  • Export map meta-data through scene flags linked grid coordinates which could be used by game systems and other modules.
Full screen preview