This package contains art, text, or software code produced using generative AI.
I used LLMs to create the code for this module. It contains no AI artwork, everything is either procedurally/mathematically generated or the art assets were licensed from talented artists. Because it was made using LLMs it is free, will always be free and even avaliable for other people to use in their commercial projects.
Map Shine Advanced
The goal of this module is to take maps in Foundry VTT and allow for a whole suite of special effects to be introduced without the user having to have huge amounts of technical knowledge. You can add particle systems, reflections and moving trees and bushes by simply naming files differently or by creating simple black and white masks/textures which show where you want the effects to be. The ultimate goal of this project is to bring animation and special effects to everyone in an always free module that you are even permitted to use for commercial projects. All I ask in return is that if you do use this module for commercially released maps that you include a link and a mention to my Patreon and / or a link to my storefront where you can support development by buying my maps.
Map Shine Advanced is a Foundry VTT module that brings a Three.js-based renderer to Foundry with a focus on cinematic 2.5D battlemaps: PBR-style surface shading, mask-driven effects, particles, and a modern post-processing pipeline.
What this module does
- Renders the scene in Three.js while Foundry continues to provide game logic + UI.
- Syncs Foundry documents (tokens, tiles, walls, drawings, notes, templates, lights) into Three.js managers.
- Uses a suffix-based texture system so map authors can provide extra masks like
_Specular,_Outdoors,_Windows, etc.
Installation
Install using the manifest URL:
https://github.com/Garsondee/map-shine-advanced/releases/latest/download/module.json
Quick start
- Install and enable the module.
- Open a Scene.
- Open the Map Shine panel:
- In the Scene Controls (Tokens), click Map Shine UI.
- In the panel, enable Map Shine for the current scene.
Gameplay mode vs Map Maker mode
Map Shine supports a hybrid workflow:
-
Gameplay Mode
- Three.js is responsible for most rendering and gameplay interactions.
- The Foundry canvas remains available for UI and tooling, but is configured as a transparent overlay.
-
Map Maker Mode
- Toggle Map Maker Mode in the Map Shine panel.
- Intended for using native Foundry tools (walls, lights, drawings, regions, etc.) without fighting the Three.js interaction model.
Map authoring: suffix-based masks
Map Shine discovers masks by searching for sibling files next to your scene background image. Use the same base filename as your background, plus a suffix.
Example (if your background is MyMap.webp):
MyMap_Specular.webpMyMap_Roughness.webpMyMap_Normal.webpMyMap_Outdoors.webpMyMap_Windows.webp
Supported formats:
webppngjpg/jpeg
Currently recognized suffixes
These are the masks currently discovered by the loader (scripts/assets/loader.js):
_Specular: Specular highlights mask_Roughness: Roughness map_Normal: Normal map_Iridescence: Iridescence mask_Prism: Prism/refraction mask_Outdoors: Indoor/outdoor mask (used for roof/indoor logic)_Windows: Window lighting mask_Structural: Legacy structural/window mask fallback_Fire: Fire placement mask_Dust: Dust motes placement mask_Bush: Animated bush texture (RGBA)_Tree: Animated tree canopy texture
Features (current)
Core rendering & syncing
- Three.js scene rendering with a dedicated render loop.
- TokenManager: token sprites synced from Foundry.
- TileManager: tiles synced from Foundry, including overhead/roof tiles.
- WallManager: walls synced and rendered in Three.js.
- DoorMeshManager: Three.js door meshes.
- GridRenderer: grid rendering based on Foundry grid settings.
- DrawingManager, NoteManager, TemplateManager, LightIconManager: Three.js counterparts for common Foundry overlays.
- MapPointsManager: v1.x map points compatibility and effect wiring.
Effects & post processing
Registered effects are orchestrated through EffectComposer (scripts/effects/EffectComposer.js). Current notable effects include:
- LightingEffect: screen-space lighting composition.
- WorldSpaceFogEffect: Fog of War rendered as a world-space plane with Foundry vision/exploration textures.
- SpecularEffect: mask-driven specular surface shading.
- IridescenceEffect: additive iridescent overlay.
- PrismEffect: masked refraction/prism look.
- WindowLightEffect: interior window light pools driven by
_Windows/_Structural. - OverheadShadowsEffect: roof/overhead shadowing.
- BuildingShadowsEffect: long shadows derived from
_Outdoors. - CloudEffect: procedural cloud shadows.
- SkyColorEffect: outdoor grading driven by
WeatherControllertime/weather. - ColorCorrectionEffect, BloomEffect, LensflareEffect, AsciiEffect.
- DistortionManager: centralized distortion composition (heat haze, etc.).
Particles
- ParticleSystem: shared particle backend.
- FireSparksEffect: mask-driven fire placement (and map-points driven fire/candle sources).
- SmellyFliesEffect: map-points driven “smart particles”.
- DustMotesEffect: dust motes (mask-driven), with planned coupling to window light.
Weather state
- WeatherController provides shared global state (precipitation, cloud cover, wind, time-of-day) and drives multiple effects.
Roadmap (planned)
This is a high-level summary of the current planning documents in docs/.
-
Cloud system expansion
- Spatial window dimming based on cloud shadows
- Sky reflections on specular surfaces
- Zoom-dependent cloud tops
-
Wall-aware lighting
- Mesh-based light polygons derived from Foundry visibility polygons
- Light accumulation buffer + composition pass
-
Vision-driven early discard / performance culling
- Centralized visibility texture for early fragment discard across expensive effects
-
Smart particles + editing
- Three.js-native map points authoring tools (interactive placement, dragging, areas)
- More effect types powered by map points (steam, lightning, etc.)