Flame3D

Flame3D is a browser-based 3D level editor and game engine built with Three.js. It combines block placement, object sculpting, terrain modeling, texture painting, skeleton animation, copy/paste/duplicate workflows, teleport blocks, media objects (text, screens, cameras), multi-world editing, a full atmosphere system, and in-editor playtesting into a single-file application.

Table Of Contents

1. Overview
2. Files
3. Running Flame3D
4. Main Menu
5. Top Bar
6. Sidebar Menus
7. Block Types
8. Object Properties
9. Movement Paths
10. Editing Controls
11. Terrain System
12. Texture Paint
13. Custom Objects
14. Sculpt Editor
15. Skeleton Animation Editor
16. Playtest Controls
17. Player Systems
18. Control Systems
19. Variables And Booleans
20. Functions Panel
21. Multi-World System
22. Atmosphere And Sky
23. Saving And Loading
24. Runtime Mode
25. Building The Editor
26. Tips And Workflow
27. Troubleshooting
28. Current Scope
29. Tips And Workflow
30. Troubleshooting
31. Current Scope

Overview

Flame3D lets you:

• Create block-based 3D levels in a live 3D viewport.
• Place walls, floors, terrain, targets, lights, spawn points, teleport blocks, and control blocks.
• Place 3D primitives (cube, sphere, cylinder, cone, pyramid, prism, torus) and 2D shapes (square, triangle, circle, polygon) with configurable sides and depth.
• Sculpt terrain with raise, lower, flatten, and smooth brushes.
• Paint object surfaces with color brushes and texture patterns (checker, brick, stripe, grid, noise, gradient).
• Copy, paste, and duplicate objects with Ctrl+C, Ctrl+V, and Ctrl+D.
• Save selections as reusable custom objects and place them from the sidebar.
• Select, move, rotate, scale, group, and ungroup objects with transform gizmos.
• Edit per-object properties such as color, solidity, groups, label, visibility, light emission, target health, switch behavior, traction, and control rules/functions.
• Add teleport blocks that transport the player between paired locations, including across different worlds.
• Place media objects: flat text panels, extruded 3D text, screen displays (color, image, video, URL, or HTML content), and in-world cameras.
• Adjust per-object metalness and roughness for shiny or matte surfaces.
• Create and edit skeleton animations with a dedicated skeleton editor.
• Create custom sculpted objects with a dedicated sculpt editor and CSG operations.
• Configure sun, moon, stars, clouds, fog, sky color, day cycle, grid visuals, render quality, and player movement rules.
• Define project-level variables and booleans for use in conditional logic.
• Build conditional player logic such as health checks, position checks, and touching a named object or group.
• Organize levels across multiple worlds with a tabbed world switcher.
• Play the level immediately in a first-person test mode.
• Save projects to browser storage or export/import JSON files.
• Export standalone game HTML or a multi-game loader HTML.

Files

• index.html: UI layout, styling, and all sidebar/topbar structure.
• main.js: Editor logic, rendering, object systems, saving/loading, playtest logic, controls/switches, and UI wiring.
• build-editor.js: Node.js build script that bundles index.html and main.js into a single standalone flame3d-editor.html file.
• flame3d-editor.html: Pre-built standalone editor HTML (generated by build-editor.js).
• README.md: Project documentation.

Running Flame3D

Because Flame3D uses ES modules and remote imports, run it through a local web server instead of opening the file directly.

Example:

python3 -m http.server 8000

Then open:

http://localhost:8000

Main Menu

The main menu appears when the app starts or when you return from the editor.

New Project

• Starts a fresh scene.
• Clears placed objects.
• Resets undo and redo history.

Import JSON

• Loads a previously exported level file.
• Restores objects, lighting settings, game rules, grid settings, and conditional triggers.

Saved Projects

• Shows projects saved in local browser storage.
• Lets you reopen a project directly.
• Lets you delete saved projects.

Top Bar

The top bar is the primary editing command strip.

Menu Selector

• Block: Object placement and transform workflow.
• Light: Light and sun settings.
• Grid: Grid display and render distance settings.
• Player: Player movement, health, fall damage, spawn protection, and conditional triggers.
• Vars: Project-level numeric variables.
• Bools: Project-level boolean flags.
• Worlds: Multi-world management.
• Files: Save, load, and export options.

Block Panel

Visible when the top menu is set to Block.

Mode Buttons

• Place: Place the currently selected block type.
• Select: Select and transform existing objects.
• Delete: Delete objects by clicking them.
• Paint: Paint surfaces with the active brush color.
• Erase: Erase objects using a configurable shape and size.

Shape Controls

Available while in Place mode.

• Sides: Number of polygon sides for shape placement (3–64).
• Depth: Thickness for 2D shape extrusions.
• Opacity: Opacity of the placed object (0–1).

Gizmo Buttons

• Move: Translation gizmo.
• Rot: Rotation gizmo.
• Scale: Scale gizmo.

Scale Side Controls

Available while scaling.

• X: Choose +X or -X growth direction.
• Y: Choose +Y or -Y growth direction.
• Z: Choose +Z or -Z growth direction.

Group Controls

• Select All: Select all placeable scene objects at once.
• Group: Create an editor group from the current selection.
• Ungroup: Remove editor grouping.

Snap

• Sets translation snap size.
• Also drives surface and ground placement snapping.

Paint Controls

Available while in Paint mode.

• Color: Active brush color.
• Mode: Draw, Erase Paint, or Fill.
• Pick: Eyedropper tool to sample a color from an existing object.
• Pattern: Texture pattern to paint (checker, brick, stripe, grid, noise, gradient).
• Color 2: Secondary color for texture patterns.
• Scale: Texture pattern scale.

Clipboard Controls

• Copy: Copy selected objects (also Ctrl+C).
• Paste: Paste copied objects (also Ctrl+V).
• Duplicate: Duplicate selected objects in place (also Ctrl+D).

Custom Objects

• Save Selection as Custom Object: Save the current selection as a reusable template.
• Saved templates are listed below and can be placed by clicking them.

Eraser Controls

Available while in Erase mode.

• Shape: Eraser cutter shape (box, sphere, cylinder, prism, square 2D, triangle 2D, circle 2D, polygon 2D).
• Size: Eraser radius.

Undo And Redo

• Undo: Reverse the latest editor action.
• Redo: Reapply the latest undone action.

Scene Commands

• Clear: Delete all placed objects.
• Save: Save the current project to browser storage.
• Export: Download level JSON.
• Game HTML: Export a standalone, self-running game HTML file from the current level.
• Loader HTML: Export a runtime HTML launcher that can import and store multiple game JSON files, then play any of them without editor tools.
• Load: Load a JSON file.
• Play: Enter playtest mode.
• Stop: Exit playtest mode.
• Menu: Return to the main menu.

Sidebar Menus

• The sidebar can be resized by dragging its edge.
• The sidebar can be collapsed and expanded.
• The sidebar has two library panes: Objects and Audio.

Block Menu

The Block menu is a categorized library of placeable objects.

• Objects / Blocks: Wall, Floor, Terrain
• 3D Primitives: Cube, Sphere, Cylinder, Cone, Pyramid, Prism, Torus
• 2D Shapes: Square, Triangle, Circle, Polygon
• Lighting: Light
• Gameplay: Target, Checkpoint, Spawn, Joint, Skeleton, Pivot, Teleport
• Control: Control, Keypad
• Media: Text, Text 3D, Screen, Camera

The selected block type is used by Place mode.

Audio Library

The Audio pane lets you import and manage audio clips for use in the project.

• Import: Import audio files into the project library.
• Imported clips are listed in the audio library panel.

Light Menu

The Light menu contains all lighting-related and atmosphere controls.

Default Light Block

• Brightness: Sets the default intensity for newly placed light blocks.

Sun

• Time: Time of day.
• North: Rotates the sun’s north alignment.
• Intensity: Sun brightness.
• Haze: Atmospheric turbidity.
• Shadow: Sun shadow range.
• Size: Sun disk size in the sky.
• Day (s): Full day/night cycle duration during playtest.
• Cycle: Enables or disables automatic day progression during playtest.

Sky

• Color: Direct sky color adjustment.

Clouds

• Enabled: Toggle cloud layer.
• Wind Speed: Cloud drift speed.
• Wind Dir: Wind direction in degrees (0–360).
• Opacity: Cloud opacity.

Stars

• Enabled: Toggle star rendering.
• Count: Number of stars (100–5000).
• Brightness: Star brightness.

Moon

• Enabled: Toggle moon rendering.
• Brightness: Moon brightness.
• Aura: Moon glow intensity.

Quality

• Shadows: Global shadow quality preset.
• Light Dist: Distance at which point lights stay active.

Grid Menu

The Grid menu now controls grid visuals and world visibility distance.

Grid Range

• Range: Number of visible grid chunks around the camera.

Floor Fill

• Color: Fill color under the grid.
• Texture: Procedural ground texture overlay. Options: None, Grass, Dirt, Stone, Sand, Snow.
• Enabled: Show or hide the fill plane.

Quality

• Render Dist: Maximum object visibility distance.

Fog

• Enabled: Toggle distance fog.
• Color: Fog color.
• Density: Fog density.
• Brightness: Fog brightness multiplier.

FOV

• Editor: Field of view for the editor camera (30–150).
• Playtest: Field of view for the playtest camera.

World Borders

• Enabled: Toggle player boundary enforcement.
• Min X / Max X: Horizontal boundary limits.
• Min Z / Max Z: Depth boundary limits.

Player Menu (Sidebar)

The Player menu contains playtest rules and conditional player logic.

Keybinds

All playtest controls are fully rebindable.

• Click any keybind button and press a new key or mouse button to remap it.
• Default bindings: W/A/S/D (move), Space (jump), R (sprint), Shift (crouch), LMB (shoot), T (free cursor), Esc (pause/exit).
• Keybind configuration is saved with the project.

Movement

• Jump: Jump force.
• Gravity: Downward acceleration.
• Gravity Enabled: Toggle gravity on or off.
• Height: Player height.
• Crouch Height: Player height while crouching (default Shift to hold).
• Sprint: Sprint speed.
• Sprint Duration: How long the player can sprint before needing to recharge (seconds).
• Sprint Recharge: Time to fully recharge sprint (seconds).
• Air Dash Enabled: Toggle mid-air dash ability.
• Air Dash Duration: Duration of an air dash (seconds).
• Allow Air Sprint: Allow sprinting in the air without prior ground momentum.

Player Identity

• Name: Player display name.
• Groups: Assign the player to named groups for use in conditional logic.

Health

• Max HP: Maximum player health.

Fall Damage

• Enabled: Toggle fall damage.
• Min Height: Minimum fall height before damage starts.
• Vel. Mult.: Fall damage multiplier.

Spawn Protection

• Timer (s): Protection duration after spawn.
• Conditions: What the protection blocks.
  • All Damage
  • Fall Only
  • Until Landed
  • None

Ground Touch Function

• Ground Touch Fn: A function name to run when the player touches the ground.

Management

• Reset Checkpoints: Reset all checkpoint positions to defaults.
• Reset Values: Reset all game variables and booleans to defaults.

Conditional Triggers

These are player-side logic rules evaluated during playtest.

Each trigger includes:

• Priority: Higher runs first.
• Mode: IF, WHEN, or WHILE.
• Condition selector.
• Action target.
• Action math.
• Optional else branch.

Supported condition sources:

• Health
• Touching
• Pos Y / Pos X / Pos Z
• Grounded
• Landed
• Distance: Distance between the player (or a named object) and a target object by name.
• Timer: Time elapsed since the trigger became active.
• Key: Whether a specific key is currently held.
• VarCmp: Compare a named project variable against a value or another variable.
• Bool: Check whether a named project boolean is true or false.
• FnDone: Whether a named control function has completed.

Touching Condition

The Touching condition supports:

• group: Match against block group names.
• name: Match against block labels.

The condition represents the player touching the matched object(s), and appears in the UI as Touching Player.

Objects can belong to multiple groups. A group match passes if any assigned group matches the condition value.

When group is selected, the input shows existing group suggestions while still allowing a new group value to be typed manually.

Distance Condition

The Distance condition checks how far the player is from a named object.

• Target object is specified by label.
• Supports all comparison operators (<, >, =, !=, <=, >=).
• Value can be a literal number or a named project variable.

Block Types

Wall

• Tall rectangular solid block.
• Solid by default.
• Good for structure and collision.

Floor

• Flat rectangular solid block.
• Solid by default.
• Good for walkable surfaces and platforms.

Terrain

• Deformable terrain block with sculpting support.
• Solid by default.
• Supports raise, lower, flatten, and smooth brush operations.
• Vertex-based sculpting in Paint mode with sculpt enabled.

Cube, Sphere, Cylinder, Cone, Pyramid, Prism, Torus

• 3D primitive shapes with configurable parameters.
• Can be solid or non-solid.
• Cylinder, cone, prism, and torus respect the Sides setting.

Square, Triangle, Circle, Polygon (2D Shapes)

• Flat 2D shapes extruded to configurable depth.
• Circle and polygon respect the Sides setting.
• Depth is set by the 2D Depth control.

Target

• Spherical target block.
• Supports target health.
• Can be shot during playtest.

Light

• Small visible point-light marker.
• Carries a real point light.
• Hidden visually during playtest while the light remains active.

Spawn

• Defines player spawn and respawn location.
• Supports Groups assignment.
• First available spawn block is used for playtest start and death respawn.
• Includes a directional indicator showing which way the player will face on spawn.

Checkpoint

• Saves the player's respawn position when touched during playtest.
• Activates on player overlap.

Joint

• Invisible connection point for linking objects together.
• Used for mechanical linkages and pivot systems.

Skeleton

• Animated skeleton model with keyframe-based bone animation.
• Edit bone structures and animations in the dedicated Skeleton Editor.

Pivot

• Rotation pivot point for grouped objects.
• Objects in the same group rotate around the pivot during function-driven movement.

Teleport

• Transports the player to a paired teleport block during playtest.
• Configured with a Pair name in the Properties panel.
• Two teleport blocks with the same pair name form a link.
• Player overlap triggers teleportation to the paired block.
• Includes a cooldown to prevent ping-pong teleportation.
• Supports Cross-World teleportation: enable the toggle and select the target world to teleport to a paired block in a different world.
• View Destination button snaps the editor camera to the paired block to preview the landing position.
• Teleport blocks are hidden during playtest.

Text

• A flat 2D panel that renders text as a texture.
• Properties: Content (multi-line), Font family (upload custom .ttf/.otf/.woff), Size, Color, background color, Align (left/center/right), bold, italic.

Text 3D

• A depth-extruded 3D text object.
• Same text properties as the flat Text block.

Screen

• A flat display panel that can show various content during playtest.
• Media type options: Color (solid color fill), Image (upload), Video (upload), URL (embed external page via iframe), HTML (inline HTML content or uploaded file).
• Interact: When enabled, the player can click the screen during playtest to open a fullscreen interactive overlay.

Camera

• A placeable in-world camera object.
• Properties: FOV, Near clip, Far clip.
• Listed under the Media category in the object library.

Control

• A visible editor block that becomes hidden during playtest.
• Uses overlap detection with the player.
• Can apply control rules when entered.
• Can run named functions that move objects or change their lighting.
• Supports Groups assignment.

Keypad

• An interactive keypad overlay that appears during playtest.
• Player enters a numeric code to trigger functions.
• Configurable with correct code, display style, and offset position.

Object Properties

The Properties panel appears when an object is selected.

Common Properties

• Type
• Name: Label used by name-based touching conditions.
• Pos
• Rot°
• Scale
• Group info for editor groups when grouped.
• Groups: Comma-separated membership list for gameplay grouping.
• Visible: In-game visibility toggle. When off, the object is hidden during playtest but still functional.

Material Properties

Available on most placeable objects.

• Metal: Metalness (0–1). Higher values give a mirror-like reflective surface.
• Rough: Roughness (0–1). Lower values produce a shinier, more specular surface.

Surface Properties

Available on walls and floors.

• Color

Solid Toggle

Available on placeable solid-capable objects.

• Solid: Controls whether the player collides with the object.

Groups Property

Available on all placeable objects.

• Groups: Suggests existing groups and accepts multiple values.
• Enter multiple groups as a comma-separated list (example: default, enemy, moving).

Traction Property

Available on solid-capable objects.

• Traction: When enabled, a grounded player standing on the object is carried along the object movement on X and Z during playtest.

Teleport Property

Available on teleport blocks.

• Pair: A text label that links two teleport blocks together. Two teleports with the same pair name form a bidirectional link.
• Cross-World: Enable cross-world teleportation and select the target world.
• View Destination: Snap the editor camera to the paired teleport's position.

Target Property

Available on targets.

• Max HP: 0 means invincible.

Switch Property

Available on visible object/block types.

• Switch: Makes the selected object shootable during playtest.
• Var: Chooses which runtime value gates the switch.
• Range: Inclusive min/max range that must be met before the switch fires its functions.
• Mode: One Shot stops after function completion, Repeat allows repeated runs.

Light Properties

Available on light-emitting objects.

• Bright: Light intensity.
• Aura: Light distance.

Emit Property

Available on non-light blocks.

• Emit: Adds or removes a point light from the selected object.

Control Rules And Functions

Available on control blocks, plus any object that has Switch enabled.

Control blocks can still add or remove player/game-rule overrides that fire on enter.

Functions support:

• Named function IDs such as 1, 2, or raiseLift.
• IF checks against another function name before the command runs.
• Targeting by group or name.
• move commands with From XYZ and To XYZ, both relative to the target object's original playtest-start position, plus animation style and duration.
• Move coordinates are relative to the target object's playtest-start position, not world origin.
• light commands that can toggle, enable, disable, set intensity, or set distance on target objects.
• Copy so you can duplicate and tweak existing functions quickly.

Supported control rule targets:

• health
• jumpHeight
• gravity
• height
• sprintSpeed
• maxHealth
• fallDamage
• fallDamageMinHeight
• fallDamageMultiplier

Movement Path

Available on most object types (not spawn, checkpoint, or trigger).

• Ready: Enable the path so it can be started by a control function.
• Draw: While checked, moving the object in the viewport places a new checkpoint at each position instead of shifting existing ones. Auto-unchecks on deselect.
• Speed: Default movement speed in units per second.
• Loop: Restart the path when the last checkpoint is reached.
• Front Axis: Which local axis (+Z, -Z, +X, -X) is treated as the object's forward face for rotation-based facing.
• + Sel Pos: Add a checkpoint at the selected object's current position.
• + Cam Pos: Add a checkpoint at the current editor camera position.
• Clear: Remove all checkpoints.

Each checkpoint row supports:

• X / Y / Z: Position in world space.
• Face: Rotate the object toward this checkpoint during movement.
• Style: Movement style — glide (smooth interpolation), strict (linear constant speed), snap (instant).
• Spd: Per-checkpoint speed override (blank uses the path default).
• Wait: Seconds to pause at this checkpoint before continuing.
• Pause: Hold at this checkpoint until a function tells the path to resume.
• on-arrive fn: A control function to run when this checkpoint is reached.
• Sel / Pick: Set the checkpoint position from the current selection or by clicking in the viewport.

Movement paths are started with a path → start function action on a control block.

Editing Controls

Mouse

• Click in Place mode: Place the selected block.
• Click in Select mode: Select one object.
• Shift + click in Select mode: Multi-select.
• Click in Delete mode: Delete the clicked object.
• Drag with transform gizmo: Move, rotate, or scale.

Keyboard In Editor

• 1: Move gizmo.
• 2: Rotate gizmo.
• 3: Scale gizmo.
• Ctrl+Z or Cmd+Z: Undo.
• Ctrl+Y or Cmd+Y: Redo.
• Ctrl+C or Cmd+C: Copy selected objects.
• Ctrl+V or Cmd+V: Paste copied objects.
• Ctrl+D or Cmd+D: Duplicate selected objects in place.
• Ctrl+G or Cmd+G: Group selected objects.
• Ctrl+Shift+G or Cmd+Shift+G: Ungroup selected objects.
• Ctrl+A or Cmd+A: Select all placeable objects.
• Delete or Backspace: Delete selected objects.
• Tab in Place mode: Sample hovered object scale for cloning.
• P: Start playtest.
• Escape: Stop playtest.

Free-Fly Editor Camera

• W A S D: Horizontal movement.
• Space or E: Move upward.
• ShiftLeft or Q: Move downward.

Playtest Controls

• W A S D or arrow keys: Move.
• R: Sprint.
• Space: Jump.
• Shift: Crouch.
• V: Toggle Dev View for normally hidden playtest blocks.
• With Dev View OFF, hidden playtest objects only hide their mesh display; lights and other gameplay systems still run.
• Left click: Lock pointer or shoot.
• T: Free cursor without pausing (toggle mouse capture).
• Escape: Exit playtest (editor) or pause game (runtime).
• P: Pause or resume game in runtime mode.

All keybinds above reflect default bindings and are fully remappable in the Player menu under Keybinds.

Terrain System

Flame3D includes a vertex-based terrain sculpting system.

Placing Terrain

1. Select Terrain from the Objects / Blocks category in the sidebar library.
2. Place terrain blocks in the scene like any other object.

Sculpting Terrain

1. Switch to Paint mode in the top bar.
2. Enable Sculpt Mode in the sidebar under Terrain Sculpt.
3. Select a brush type: Raise, Lower, Flatten, or Smooth.
4. Adjust Radius and Strength to control the brush size and effect intensity.
5. Click and drag on a placed terrain block to sculpt it.

Brush Types

• Raise: Push vertices upward to create hills and ridges.
• Lower: Push vertices downward to create valleys and depressions.
• Flatten: Level vertices to a consistent height.
• Smooth: Average nearby vertex heights to reduce jagged surfaces.

Texture Paint

Texture Paint lets you apply procedural patterns to object surfaces in addition to flat colors.

Using Texture Paint

1. Switch to Paint mode.
2. In the sidebar under Texture Paint, select a Pattern.
3. Optionally set Color 2 for the secondary pattern color.
4. Adjust Scale to control pattern density.
5. Click on objects to apply the texture.

Available Patterns

• None: Color only (default flat color painting).
• Checker: Alternating color checkerboard.
• Brick: Brick wall pattern.
• Stripe: Horizontal stripes.
• Grid: Grid line pattern.
• Noise: Procedural noise texture.
• Gradient: Smooth gradient between two colors.
• Wood: Wavy wood grain pattern.
• Cobblestone: Irregular rounded stones with mortar.
• Marble: Veined marble pattern.
• Custom Image: Upload any image file to use as a paint texture.

Custom Objects

You can save object selections as reusable templates and place them later.

Saving a Custom Object

1. Select one or more objects in the scene.
2. Click Save Selection as Custom Object in the sidebar under Custom Objects.
3. Enter a name for the template.

Placing Custom Objects

• Saved templates appear in the Custom Objects list in the sidebar.
• Click a template to place a copy of it in the scene.
• Templates include all object properties, positions, rotations, and scales relative to the selection center.

Managing Custom Objects

• Custom objects are saved with the project.
• Delete templates from the list when no longer needed.

Sculpt Editor

The Sculpt Editor is a dedicated overlay for creating custom sculpted objects using CSG (Constructive Solid Geometry) boolean operations.

Opening the Sculpt Editor

• Select a terrain or sculpted object and open its sculpt editor from the Properties panel.

Features

• Add primitive shapes (box, sphere, cylinder) as sculpt operations.
• Boolean operations: Union, Subtract, Intersect.
• Full TransformControls with Move, Rotate, and Scale gizmos (keyboard shortcuts 1, 2, 3).
• Click to select primitives in the 3D viewport.
• Real-time preview of the combined CSG result.
• Undo support for transform changes.

Skeleton Animation Editor

The Skeleton Animation Editor lets you create bone-based character animations.

Features

• Visual bone hierarchy editor with add/remove/rename controls.
• 3D preview of the skeleton with interactive bone manipulation.
• Timeline with keyframe support for bone rotations.
• Play, pause, and scrub through animations.
• Animations are saved with the skeleton object and exported with the project.

Player Systems

Health

• Player starts with Max HP.
• Health updates live in the playtest HUD.
• If health reaches 0, the player respawns.

Sprint

• A sprint meter appears below the health bar during playtest.
• Sprinting drains the meter; releasing sprint recharges it.
• Sprint cannot be used in the air unless the player was already sprinting before leaving the ground, or Allow Air Sprint is enabled.
• Air Dash allows a brief mid-air sprint burst when enabled.

Respawn

• Respawn uses the current spawn block’s actual world position.
• If no spawn block exists, playtest falls back to the editor camera start position.

Fall Damage

• Uses the configured minimum height and multiplier.
• Can be blocked by spawn protection depending on settings.

Spawn Protection

• Timer-based protection can block all damage, only fall damage, or stay active until the first landing.

Traction

• If the player is grounded on a moving, solid object with Traction enabled, the player is carried along the surface on X and Z.
• Carry uses previous-frame support checks to stay more stable when platforms move quickly.

Control Systems

Control Blocks

• Control blocks check player overlap using AABB overlap during playtest.
• On enter, they apply configured control rules.
• Controls can run multiple named functions across multiple target objects.
• Functions can move targets or change target lighting.
• Function dependencies let one function wait for another function to be met.

Shootable Switches

• A switch-enabled object can be pressed by shooting it.
• The switch only fires if its selected runtime variable is inside the configured min/max range.
• When fired, it runs the same function list used by control blocks.

Conditional Triggers

• These run continuously during playtest.
• They can change player values and game rule values.
• IF: Fires once when the condition becomes true.
• WHEN: Fires every frame while true.
• WHILE: Fires on a repeat interval while true.

Variables And Booleans

Project-level variables and booleans can be defined in the Player menu and used across conditional triggers, control functions, and switch logic.

Variables

• Numeric values that persist during a playtest session.
• Add, rename, or remove variables from the Player panel.
• Can be read and written by conditional triggers and control functions.

Booleans

• True/false flags that persist during a playtest session.
• Add, rename, or remove booleans from the Player panel.
• Useful for gating logic (e.g., "door unlocked", "boss defeated").

Functions Panel

The Functions panel is a dedicated right-side panel for managing all control functions across the project.

• Searchable list of all functions defined on control blocks and switch-enabled objects.
• Functions can be organized into collapsible groups.
• Add Function: Create a new function entry.
• Add Group: Create a new function group for organization.
• Each function supports targeting by group or name, with move and light commands.
• Functions can have IF dependencies on other function names.

Multi-World System

Flame3D supports multiple worlds within a single project, allowing you to build separate areas or levels.

• A tab bar at the top of the editor shows all worlds.
• Add World: Create a new world tab.
• Clicking a world tab switches the active editing world.
• Each world has its own set of objects.
• During playtest, all worlds are loaded together into a single scene.
• Objects remember which world they belong to through save/load.

Atmosphere And Sky

Sun And Sky

• The sun updates lighting, sky appearance, and shadow behavior.
• Time can be fixed or animated during playtest.
• Sun size, sky color, and atmospheric haze are independently adjustable.

Moon And Stars

• The moon and stars appear during nighttime in the day cycle.
• Both can be toggled and configured for brightness.
• Star count is adjustable.

Clouds

• A cloud layer can be toggled with wind speed, direction, and opacity controls.

Fog

• Distance fog with adjustable color, density, and brightness.
• Helps set atmosphere and hide pop-in at render distance boundaries.

Point Lights

• Dedicated light blocks create point lights.
• Other blocks can emit lights through properties.
• Point lights are distance-culled using Light Dist.

Quality Settings

• Render Dist: How far blocks stay visible.
• Shadows: Shadow quality preset.
• Light Dist: Distance at which point lights render.

Saving And Loading

Save Project

• Stores the current project in IndexedDB browser storage (migrated from localStorage for larger project support).
• Includes settings and placed objects.
• Auto-restore periodically saves editor state in the background so work can be recovered after unexpected closures.

Export JSON

• Downloads the current level as JSON.

Export Game HTML

• Builds a self-running HTML file that includes the current level and runtime.
• Runs in play mode with editor tools disabled.
• Includes an in-game runtime settings panel for quality and day-cycle tuning.
• In-game P key or the ⏸ Pause HUD button opens the pause menu.

Export Loader HTML

• Builds a runtime-only HTML file with no editor tools.
• Provides a game library panel where multiple JSON files can be imported and kept in browser storage.
• Lets you launch any imported game from that library, similar to a lightweight game launcher flow.
• Each library entry stores the level name, object count, play duration, and last-played timestamp.
• Supports importing additional JSON files into the library at any time.
• Library data is stored using the key flame3d_runtime_library_v1 in browser local storage.

Load JSON

• Imports a previously saved JSON file.

Saved Data Includes

• Scene objects (per world)
• Sun, moon, stars, clouds, and sky settings
• Fog settings
• Game rules (movement, health, fall damage, spawn protection, sprint, air dash)
• Grid fill and world border settings
• FOV settings
• Conditional triggers
• Variables and booleans
• Object labels, groups, control rules/functions, switch settings, light values, visibility, traction, and target health
• Audio library entries

Runtime Mode

Runtime mode is active when a standalone game HTML is opened. It hides all editor UI and switches the app to a pure gameplay experience.

Runtime Flags

The following globals control which runtime mode is active. They are set by the exported HTML before the main script runs.

Flag	Type	Description
__FLAME3D_RUNTIME_MODE__	boolean	Activates runtime mode and hides editor UI.
__FLAME3D_RUNTIME_LOADER__	boolean	Shows the game library overlay instead of auto-starting.
__FLAME3D_RUNTIME_AUTOSTART__	boolean	Immediately starts the embedded level on load.
__FLAME3D_EMBEDDED_LEVEL__	object	Level JSON payload embedded in the page for autostart.

Runtime HUD

In runtime mode, a minimal HUD replaces editor controls.

• ⏸ Pause button: Opens the pause menu.
• ⚙ Runtime button: Toggles the runtime settings panel (quality and day cycle).
• 📚 Library button (loader mode only): Returns to the game library overlay.

Pause Menu

Opened with P, Escape, or the ⏸ Pause HUD button. Pointer lock is released while the menu is shown.

• Resume: Closes the menu and re-locks the pointer.
• Save Progress: Saves the current position, health, hits, and optimizer state to the active library entry.
• Save and Quit: Saves progress and returns to the game library overlay.
• Quit Without Saving: Returns to the game library overlay without saving.
• Restart Level: Resets the level to its initial state and restarts without saving.
• Settings: Inline quality controls (shadow quality, render distance, light distance, auto-performance, auto-visual) available directly in the pause menu.

Progress Snapshot

When saving progress, the following state is captured and can be restored on next launch:

• Player world position (X, Y, Z)
• Player look direction (yaw and pitch)
• Vertical velocity
• Current health
• Shot and target hit counts
• Adaptive optimizer state (current quality profile index)

Progress is stored per library entry and survives page refreshes as long as browser local storage is not cleared.

Runtime Settings Panel

Accessible via the ⚙ Runtime HUD button or inside the pause menu. Controls:

• Shadow Quality: Off, Low, Medium, High.
• Render Distance: Block visibility cutoff in world units.
• Light Distance: Point light render cutoff in world units.
• Auto Performance: When enabled, the adaptive optimizer can lower quality to maintain frame rate.
• Auto Visual: When enabled, the adaptive optimizer can raise quality when performance is good.

Adaptive Performance Optimizer

When active, the optimizer monitors frame rate using an exponential moving average and automatically adjusts quality.

• Checks every 5 seconds (configurable via RUNTIME_OPTIMIZER_CHECK_INTERVAL_MS).
• After adjusting, waits at least 8 seconds before adjusting again (configurable via RUNTIME_OPTIMIZER_COOLDOWN_MS).
• Requires three consecutive low-FPS checks before stepping quality down (guards against brief spikes).
• Requires three consecutive high-FPS checks before stepping quality up.
• Quality profiles in order: Performance, Balanced, Quality, Ultra.
• Auto Performance and Auto Visual can be individually toggled.
• State is saved as part of the progress snapshot.

Game Library

The game library overlay is shown in loader-mode exports and when returning from a level.

• Import JSON game files using the Import JSON button.
• Each entry shows the game name, object count, last-played date, and total play time.
• Play launches a fresh run; Continue restores saved progress if available.
• Remove deletes the entry and its progress from local storage.
• Library entries are stored in flame3d_runtime_library_v1.

Building The Editor

A Node.js build script bundles the editor into a single standalone HTML file.

node build-editor.js

This reads index.html and main.js, inlines all code, and outputs flame3d-editor.html. The standalone file can be opened directly or hosted without needing a separate JS file.

Tips And Workflow

1. Start by choosing a block type from the Block menu.
2. Build structure with walls and floors.
3. Add a spawn block before playtesting.
4. Use labels and groups early if you plan to use touching conditions.
5. Use control blocks for zone-based player changes.
6. Use conditional triggers for logic based on health, position, grounded state, or touching rules.
7. Save to browser storage often and export JSON snapshots when needed.

Troubleshooting

The App Does Not Load

• Make sure you are serving the files through a local web server.
• Do not open index.html directly as a file URL.

Lights Or Shadows Look Wrong

• Check the Light menu Shadows setting.
• Increase Light Dist if point lights disappear too early.
• Adjust sun Intensity, Haze, and Shadow range.

I Respawn In The Wrong Place

• Make sure a spawn block exists.
• The first spawn block in the scene is used.
• Respawn now uses the spawn block’s actual world placement.

Touching Conditions Do Not Fire

• Confirm the target object has the expected Group or Name.
• For group checks, verify the group text matches the condition.
• For name checks, verify the label is set in the Properties panel.

Current Scope

Flame3D currently focuses on:

• In-browser 3D level editing with multi-world support
• Immediate FPS playtesting with sprint, crouch, air dash, and world borders
• Block/object property editing including visibility, traction, and switches
• 3D primitive and 2D shape placement with configurable polygon sides and depth
• Terrain placement and vertex-based sculpting with multiple brush types
• Texture painting with procedural patterns (checker, brick, stripe, grid, noise, gradient)
• Copy, paste, and duplicate workflows for rapid level building
• Custom object templates for saving and reusing selections
• Sculpt editor with CSG boolean operations and full transform gizmos
• Skeleton animation editor with bone hierarchy and keyframe timeline
• Teleport blocks for player transportation between paired locations
• Paint and eraser tools for surface editing
• Full atmosphere system: sun, moon, stars, clouds, fog, sky color
• Project-level variables and booleans for game logic
• Functions panel with search, groups, and dependency chains
• Trigger and conditional logic authoring
• Audio library for importing and managing sound clips
• Media objects: flat text panels, extruded 3D text, screen displays (color/image/video/URL/HTML), and in-world cameras
• Per-object metalness and roughness material controls
• Procedural ground textures for the grid floor (grass, dirt, stone, sand, snow)
• Fully rebindable player control keybinds
• Cross-world teleportation between paired teleport blocks in different worlds
• Movement path draw mode for placing checkpoints by moving the object in the viewport
• Extended conditional trigger conditions: distance, timer, key press, variable comparison, boolean, and function-done checks
• Project save/load workflows backed by IndexedDB with auto-restore
• Standalone game export with full runtime mode
• Standalone editor export via build script
• Game library and loader workflow for distributing multiple levels
• Adaptive performance optimization during runtime gameplay