The Horizon Editor

Orientation

Editor Layout

The editor is a single window built from dockable panels around a central Scene viewport. Double-clicking assets opens additional full-size asset editor tabs (material graphs, widget designer, particle graphs …) alongside the Scene tab.

The footer bar holds Undo/Redo buttons on the left, the status text in the centre, and the current resolution and FPS on the right. Log output is written to HorizonEngine.log next to the executable (truncated each launch).

Starting point

Project Hub

The editor launches into the Project Hub: a list of known projects plus a New Project form. Creating a project asks for a template, a scripting language, a name and a directory.

Templates

Scripting language

The language is a whole-project choice, fixed at creation. It gates which gameplay-logic assets the Content Browser offers and which components appear:

Opening a project from the file manager

A project file (.heproj) opens in the editor with a double click in Finder, Explorer or your Linux file manager. The editor takes it the same way the Hub's own Open does: if another project is open and has unsaved changes, it asks first, and if that very project is already open, nothing happens. The path also works on the command line, as in HorizonEditor MyGame.heproj. If a .heproj named at launch is missing, or the path is a folder, the editor shows the Project Hub with the reason instead of the last project. Anything that is not a .heproj is only noted in the log.

On Windows and Linux there is nothing to set up for this: the editor registers the file type for you every time it starts, as described below. On macOS the app itself carries it.

Registering the file type

On Windows and Linux the editor checks early in every start, before the first frame, whether .heproj already opens with this editor. The check is cheap: a few registry values on Windows, a few small files on Linux. Only when something is missing or different does a short background task write, so the start never waits for it. The registration is for your user only, needs no administrator rights, and doing it again changes nothing. A freshly unpacked editor therefore has to be started once before a double click can find it. If you move the editor or update it into another folder, the registration still points to the old place, and the next start rewrites it to the new one. On Windows the editor also tells Explorer, so icons refresh without signing out; on Linux it refreshes the desktop's databases where the tools for that exist.

Headless runs and runs with a hidden window do not register, and neither does an editor that runs without its FileTypes folder next to it, such as a plain build folder instead of an unpacked package.

The editor does not take .heproj away from another program. If on Windows the .heproj association, or the Open with ▸ Always choice you made in Explorer, names another program, or on Linux your mimeapps.list names another default application, the editor writes nothing, adds one line to the log and shows one notification that says how to switch. It shows it once for each such program, because the editor remembers which one it told you about. To switch, choose the editor under Open with in your file manager, or run the script from the FileTypes folder, which overwrites the association. On Windows a choice stored by Open with ▸ Always outranks the registry, so use Open with there.

You can turn the registration off with the checkbox Register .heproj with this editor, under File types at the end of Edit ▸ Preferences ▸ Editor ▸ Tool Status. macOS does not show it, because the app needs no registration. It is on by default and is stored in the editor's config.json as RegisterHeprojFileType. With it off, the editor never touches the file association. Switch it off before you remove the registration with the unregister script, because otherwise the next start registers it again.

Each start adds one line to the editor log that says what was done: registered, updated, already registered, left alone because of a named program, skipped or failed. A failure is a warning, not an error, and the editor starts as usual.

As a fallback, HorizonEditor --register-file-types (HorizonEditor.exe on Windows) does the same registration at once and without opening a window. It ignores the checkbox, because you asked for it, but like the start it leaves a program that already handles .heproj alone. It prints one line, a keyword and a sentence, and exits with a code you can test in a script:

The scripts in the FileTypes folder do the same by hand. Unlike the editor, they take over a .heproj that another program owns.

Where you live

Scene Viewport

The Scene panel renders the world through the editor camera and carries an inline toolbar: a mode selector (View / Landscape), the gizmo buttons Move / Rotate / Scale, a gizmo-space combo (Local / World), a Screen ring toggle for the rotate gizmo, and the centred Play / Stop button.

Camera navigation

Gizmos

W / E / R switch between translate, rotate and scale (mirrored by the toolbar buttons). The space combo toggles manipulation in local or world axes; Screen ring adds the view-axis outer ring to the rotate gizmo. Gizmos are suppressed while flying, while Alt is held, and in Landscape mode. Every edit is undoable (Ctrl/Cmd+Z).

Static-mesh assets can be dragged from the Content Browser into the viewport to spawn an entity at the drop point.

Hierarchy

World Outliner

The Outliner shows the entity hierarchy of the active scene. Drag an entity onto another to reparent it. Right-click the background for Create Entity; right-click an entity for Create Child Entity, Rename, Save as Prefab and Delete.

The special Sky and Weather entities (added through the Environment window) appear here like any other entity — select them to edit the full sky and weather settings in the Details panel. The Sun and Moon are children of the Sky entity and are driven automatically.

Properties

Details Panel

The Details panel lists every component on the selected entity with full property editors, and ends with the Add Component button. Components you can add directly: Transform, Transform 2D, Mesh, Skeletal Mesh, Nav Mesh, Nav Agent, Material, Camera, Light, Rigid Body, Collider, Script (Lua/Python projects), Audio Source, Audio Listener, Particle System, LOD and Foliage.

Additional components appear with full editors when an entity carries them through other workflows — the Animator family (Animator, Animator Blend, Animator State Machine, Property Animator), Character Controller, Terrain, the in-world UI components, and the Environment/Weather editors on the Sky and Weather entities.

The complete component reference — every property of every component — lives on Scenes & Entities.

Assets

Content Browser

A folder tree on the left, an asset grid on the right. There are up to three roots:

• Content — your project's assets.
• Engine — built-in default assets (read-only).
• Source — the C++ class tree (C++ projects only).

Creating assets

Right-click the background (or an item's Create Asset submenu) to create an asset; a naming popup follows immediately. Always available:

Gameplay-logic assets depend on the project language: HorizonCode Class plus Player Controller / Player Character (HorizonCode projects), Script (Lua/Python projects), or C++ Class (C++ projects — writes a .h/.cpp pair under Source/).

Importing

Assets ▸ Import Asset… (or a folder's Import context item) dispatches by extension to the mesh, texture, audio, material and font importers. Audio import currently accepts WAV.

An imported asset remembers where it came from, so its right-click menu offers Reimport — it re-reads the original file and keeps the asset's identity, which means every reference to it survives. The entry is only there when a source path was actually recorded; nothing guesses one.

Finding things

The box above the grid searches the folder you are in and everything under it — a search that only looked at the level you already opened would require you to know the answer before asking the question. Beside it, a type filter narrows to scenes, materials, meshes, prefabs, widgets and the rest, and a single × clears both at once.

While a search or filter is active the grid shows matches from the whole subtree rather than the current folder's contents, so a hit three folders down is one click away.

Selecting, moving, renaming

Moving an asset carries everything that pointed at it — other assets' stored references, the asset's own embedded path, its thumbnail — over to the new location. A move that quietly broke those is how a project loses its materials.

With several assets selected, Rename becomes a pattern rename: find and replace inside the name, a prefix, a suffix, and a live preview of every resulting name before anything is written. Renaming twenty files one dialog at a time is the kind of task nobody does, so nobody tidies up.

Deleting, and what depended on it

Deleting asks first — a red menu entry is not a confirmation — and the confirmation says who still needs the file. The scan runs in the background over the whole project and reports each referrer, plus how it points at the asset: a stored path can be repaired by renaming instead, while a scene's stored id can only dangle once the asset is gone.

Deleting a folder scans everything inside it the same way. And when a file cannot be read, the dialog says so rather than reporting “nothing references it” — “I could not check” and “I checked and found nothing” are different answers, and only one of them is safe to act on.

Find References

The same scan is available on its own, from any asset's right-click menu, without having to threaten to delete something to see the answer. It reads both encodings a reference can take: the path stored inside another authored asset, and the UUID stored in a scene.

In a collaboration session

The content browser is part of a session. Creating is open to everyone; deleting, renaming and moving are requests the host answers; an asset somebody else is editing carries a padlock in their colour. See Assets in a Session.

Assets

Engine Content

The Engine root holds the assets that ship with the engine — default materials, primitive meshes, the fonts the editor draws with. They are read-only, and an engine asset resolves through three places in order.

Overriding one

Saving a change to an engine asset writes a copy under your project's Engine/ folder; the shipped original is never touched, and every other project on the machine keeps the version it had. The tile then offers Revert to Default, which removes your copy and lets the engine's own version show through again.

Assets that are not downloaded yet

The engine content library is larger than the install. Assets that live only on the server still appear in the browser as tiles — you can see what exists before deciding to pull it — and the first thing that needs one fetches it into the machine-wide cache.

A downloaded copy can be given back with Remove Local Copy. It is deliberately not called “Delete”: nothing is lost. The asset goes on existing on the server, the tile turns back into the remote-only placeholder it was before, and the next use fetches it again. What it reclaims is disk — the cache is shared by every project on the machine, so it only ever grows.

Feedback

Notifications

A bell in the footer collects the things that happened without you doing them: a background scan that could not read a file, an import that finished, a collaboration request nobody answered, a peer that refused a file. It carries a count of what you have not read, and clicking it expands a flyout with the list.

It is not a log. A log answers “what happened”; this answers “what still needs you” — entries are written in sentences, and the ones about a particular file carry its path. Repeated identical messages collapse into one row with a count, and when the list is full it drops the oldest message you have already read, so an unread problem is never pushed out by a run of chatter.

Deep dives

Asset Editor Tabs

Double-clicking an asset opens a dedicated editor tab next to the Scene tab. Material graphs, HorizonCode graphs, the Level Script, the Game Instance, particle graphs and animator state machines all share one node-graph canvas — learn it once (pan with the right mouse button, box-select with the left, zoom with the wheel) and every graph editor works the same way.

Terrain

Landscape Mode

Switch the viewport toolbar's mode selector to Landscape and the Quick Settings panel becomes the terrain tool.

Create Landscape

With no terrain in the scene the panel shows a creation form: Width (X), Depth (Z), Resolution (2–512), Height Scale, and procedural noise — Seed (0 = flat), Octaves, Frequency, Lacunarity, Gain — with a live grid preview. Creating adds a Terrain entity with a default terrain material. The seed noise is baked once into editable heights; from then on the terrain is a plain heightfield your brushes edit directly.

Sculpting

Six brush tools: Raise, Lower, Smooth, Flatten, Ramp, Roughen, with Radius (0.5–500 m), Falloff and Strength. Drag with the left mouse button in the viewport to sculpt — Flatten pulls toward the height under the drag-start point, Ramp blends between two dragged points. Reset Sculpting clears all edits. Strokes only regenerate the terrain chunks they touch, so sculpting stays fast on large terrains.

Mountain

The seventh tool, Mountain, grows a whole formation inside an area instead of under a brush. Drag across the ground to mark the area, as a Rectangle (corner to corner, the mountain fills the ellipse inside it) or a Circle (centre to rim); the outline follows the pointer and the mountain appears when you let go, as one undo step. It is added on top of the ground that is there, so earlier sculpting stays underneath, and outside the area nothing moves. Max Height is how far the tallest point rises (negative digs a basin), Falloff the width in metres of the slope back down to the rim, and Roughness, Octaves and Frequency shape the noisy relief. The same Seed, area and settings give the same mountain again; New Seed picks another. MCP clients reach the same operation through terrain_mountain.

Terrain renders as a grid of chunk entities with automatic LOD meshes and skirt geometry — details under Rendering ▸ Performance. Scatter vegetation with the Foliage component.

Sky & weather

Environment Window

View ▸ Environment manages the two special scene entities:

• Sky — Add Sky / Remove Sky. The Sky entity carries the Environment component (atmosphere, day-night cycle, clouds, stars, fog …) and owns the Sun and Moon as child entities. Removing it leaves a flat background colour.
• Weather — Add Weather / Remove Weather. Requires a Sky to drive; carries the Weather component (presets, precipitation, auto-cycle).

The window only adds, removes and selects — the actual settings are edited in the Details panel. The full parameter reference is on Rendering & Environment.

Test it

Play Mode

The Play button in the Scene toolbar starts a play-in-editor session; Escape (or the Stop button) ends it. Entering play initialises physics, fires Play on Start audio, starts scripts and spawns HorizonCode player classes. While playing, physics steps at a fixed timestep, scripts receive onUpdate, collision events dispatch, widgets tick, and input actions fire.

The scene renders through the camera marked Main Camera (or the first camera found). On stop, the world is restored to its pre-play state and a Play Session Report window summarises the session. Animation, navigation and particle systems also run outside play mode so you can preview them while editing.

C++ projects

Building Game Logic

Build ▸ Build and Reload Game Logic compiles a C++ project's Source/ folder into its native GameLogic library and swaps the result into a running play session — the session keeps going, with the new code in it.

The compile runs in the same Build window the export uses, in two steps: Compile, then Reload. The second one either happened or it did not, because compiled and running are different answers and the window has to be able to say which one it got to. Compiler warnings and errors are listed as they arrive; Build Again repeats the module build, not a project export.

• Outside Play mode it only builds. That is not a failure — the module that was just built is exactly what the next Play loads.
• Entering Play loads the built module, hands it the engine service tables and calls onStart; leaving Play calls onStop and unloads it. With no module built yet, the log says which menu item builds one.
• Other project languages get a note instead of a build: Lua, Python and HorizonCode script their gameplay in a language that needs no compiler.
• Toolchain — needs CMake and a C++ compiler, and engine headers to compile against. Preferences ▸ Tools ▸ Status shows what was found and can install what is missing.

What the module can reach once it is loaded — physics, input, content and savegames, through the injected service tables — is described under Scripting ▸ Native C++.

Measure

Performance Profiler

View ▸ Performance Profiler opens the engine's built-in profiler. Among its tabs:

Streaming cells in the editor

A large scene can stream in squares: the game loads the cells around its camera and drops the far ones (see large worlds). The Streaming tab splits the open scene: pick a cell size and, if you like, the load and unload radius, then Split into Streaming Cells. Placed meshes, point and spot lights, static bodies and decals move into one scene file per square, in a folder named after the scene; everything that has to be there all the time stays. The scene must have been saved once, and the split is one undo step that you keep by saving.

Show ▸ Streaming Cells in the Scene window draws the squares on the ground: green ones the game would load from where the editor camera stands, orange ones it keeps once loaded, grey ones it drops, with the two radii as rings. To change what is in the cells, Merge Cells into the Scene brings them back as ordinary entities, in their folders and with their identities, and the cell list goes; split again when done. Neither is offered while playing or inside a collaboration session.

Setup

Preferences

Edit ▸ Preferences (Ctrl/Cmd + ,) holds machine-level settings:

• Renderer — graphics backend picker (OpenGL everywhere; Metal on macOS; Direct3D 11/12 on Windows; Vulkan where enabled), VSync, GPU weather particles.
• Post-processing — Bloom (threshold, intensity) and ambient occlusion (method SSAO / HBAO / GTAO, radius, intensity). See Post-Processing.
• Source Control ▸ Repository — one page for both halves of git: what the machine has (git, Git LFS, your commit identity, the credential helper) and what the project has (initialise, remote, access token, auto-push). Commits and pushes themselves live in View ▸ Source Control.
• Tools ▸ Status — everything the editor needs from outside itself in one table: git and Git LFS, CMake and a C++ compiler, the local network and the router. Rows that are not green offer a Fix. A "C++ Toolchain Not Found" dialog also appears at startup when CMake or the compiler are missing, offering automatic installation — the toolchain is needed for C++ projects and for compiling HorizonCode at export.
• Collaboration — whether the editor announces and listens for sessions on the local network; whether it will carry large assets (off by default, and greyed out while a session is running); and the ceiling on a single transfer, 1–512 MiB. Your display name, colour and avatar are set in the Collaboration window itself.
• Feedback — small, optional signs that something just worked. A save, a finished build, an import, a clean HorizonCode compile, a commit or push and the end of the tutorial each show a word in the middle of the footer (Saved, Build succeeded, Compiles clean, Committed and pushed…) with a drawn check mark, then the footer returns to Ready. Nothing opens, nothing takes focus, nothing waits for it. The compile readout in a graph's strip writes the same check; a compile that found a problem makes the offending node's red halo pulse once, and a new problem notification rings the footer bell once (Problem Pulse). Beside Ready the footer can show today's builds and your days in a row; hovering them shows the last seven days. No points, levels or goals.
• Feedback sounds — off until you switch on Success Sound. Then each event has its own quiet tone and its own switch with a Preview button: save, build, build failed, import, compile, compile failed, commit, tutorial and problem. Sound Volume sets them all; Mute Editor Sounds silences them at once and keeps the switches as they are. The build, commit and problem tones only play while the editor is in the background; at most one tone plays every two seconds, the problem tone at most every thirty, and none during Play. They play on an output of the editor's own, which is only opened while sound is on, so the project's mixer and mute do not touch them. Reduced Motion follows the system: check marks appear whole, rings and lines stop moving, fades stay.

Reference

Menu Reference

On macOS the same commands live in the native menu bar (⌘N, ⌘O, ⌘S, ⇧⌘S, ⌘,, ⌃⌘F …), plus the standard app and window menus.

Muscle memory

Shortcut Reference

In play mode the default fly camera uses W A S D, E/Space up, Q/Ctrl down and Shift for 3× speed.