# Working in the editor

For artists, level designers, and other team members who work without writing code. This guide covers opening a prepared project, placing and editing content, testing it, and saving your work. You do not need to read the engine architecture or learn Zig to follow it.

## Before you start

Ask your project maintainer for a compatible Hikari editor and a project folder containing `hikari.project.json`. Opening a project compiles its game module automatically, even if you only edit art. The editor therefore needs the matching engine SDK and Zig toolchain; a packaged editor can include both. If compilation fails, the splash opens the compiler output; share it (or the file **Reveal Log** shows) with the maintainer. [Project setup and toolchain troubleshooting](/docs/systems/editor-project-selector.md) explains the requirements.

Hikari's supported editor platforms are Apple Silicon macOS and Windows. The current macOS product requires macOS 26 and a compatible Metal GPU. Linux support is incomplete. See [Platforms](/docs/systems/platforms.md) for the development requirements.

Launch the editor, choose **Open Project…**, and select the project folder. If a version warning appears, check that you have your team's intended editor build before continuing. The editor may restart as it opens the project.

## Find your way around

| Area | What you use it for |
|---|---|
| Viewport | See the scene and manipulate selected objects |
| Hierarchy | Find and select actors: the objects placed in the scene |
| Inspector | Edit the selected actor's transform and component properties |
| Asset Browser | Find, import, organize, and open project assets |
| Console | Read import, compilation, and runtime errors |
| Toolbar | Choose transform tools; enter Play, Pause, or Stop |

A **scene** is a saved arrangement of actors. An **actor** is an object with a transform and components. A **component** supplies a capability, such as rendering a model, emitting light, or playing sound. The project supplies available actor types and gameplay components; you can place and configure them without implementing them yourself.

Use **File → Open Scene** or open a scene from the Asset Browser. Select an actor in the Hierarchy, then choose **Edit → Focus** or press **F** while you are not typing. This brings the selection into view. The Hierarchy search matches actor names, IDs, and types; clear the search if an object seems to have disappeared.

## Place and arrange content

1. Open a scene in **Edit** mode.
2. Use the Hierarchy's **+** menu to create an Empty, Light, Camera, or another available type. The **Game** section contains types supplied by your project.
3. To place existing art, use the **Place…** entries and choose the asset. Use the Asset Browser to inspect a model or texture before placing it.
4. Select the new actor. Edit **Position**, **Rotation**, and **Scale** in the Inspector, or use the viewport's transform tools.
5. Give the actor a recognizable name. Save the scene with **File → Save**.

The world uses **Y up**. Cameras look along their local **negative Z** axis. For example, a camera at positive Z with zero rotation looks toward the origin. An imported model's scale and orientation depend on its source content; inspect it before duplicating it throughout a level.

| Action | Shortcut |
|---|---|
| Move / Rotate / Scale | W / E / R |
| Focus selection | F |
| Local / World transform space | X |
| Toggle snapping | Shift+S |
| Duplicate selection | Shift+D |
| Rename | F2 |
| Undo / Redo | Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z |
| Save scene | Cmd/Ctrl+S |
| Command palette | Cmd/Ctrl+P |

These shortcuts apply when the editor owns keyboard focus, not while typing into a text field. Use the menus or toolbar if a shortcut is unavailable. **Local** uses the selected actor's axes; **World** uses the scene axes. Snapping helps align repeated pieces.

## Import and organize assets

Use the Asset Browser's **Import…** action. Choose a source file, then its destination and name. Hikari's asset processor, **Shinra**, converts source art into the runtime format; this conversion is called *cooking*. Wait for it to finish before judging the preview.

Double-click an asset to open its detail window. Models have a 3D preview; skinned models also show clips and playback controls. Textures offer channel inspection and zoom. Materials, animation graphs, particles, and UI documents have their own authoring surfaces. A plain shader-authored material is a previewable asset; it is not automatically converted into a visual material graph.

Rename, move, duplicate, and delete assets through the Asset Browser. Its operations update recognized project references, and deletion reports affected documents and can offer a replacement. Moving files outside the editor does not perform that reference update.

Edit source files in the project. The `.engine/` directory and packaged `data/` folders contain generated files; changes there can be overwritten by cooking or building. Keep source art, scenes, and settings in your team's version-control workflow.

## Test without losing authored work

**Edit** changes the scene document. **Play** runs a disposable copy to test gameplay, scripts, and physics. **Stop** returns to the retained Edit scene, including changes you had not yet saved to disk. Play-time movement and runtime spawns do not become saved scene edits.

1. Save the scene before testing so your work is also safe on disk.
2. Press **Play** and wait for **Starting…** to finish.
3. Click the viewport when the game needs mouse capture. **Escape** releases capture.
4. Use **Pause** to inspect a moment. **Unpossess** lets the editor camera look around independently of the game camera; it does not pause the simulation.
5. Press **Stop** before making changes you want to keep.

The Play Inspector shows live values but is read-only. Asset changes are cooked in the background, but their application to the scene is deferred during Play. Stop to see a changed material, texture, or model applied in Edit.

For scene transitions and programmer controls, see [Play, Edit, and scenes](/docs/tutorials/play-edit-and-scenes.md).

## Choose the right settings

**File → Project Settings** edits project configuration. Read the apply-timing note next to a setting: some changes apply on Save, others require restarting the editor, launching a standalone game, or building a package. Rendering and Quality changes apply live on Save.

**File → Editor Settings** controls your editing environment, including theme, interface size, language, accessibility, and scrolling. These preferences are separate from the game's authored settings.

The **Environment** panel can preview a time of day for a scene using Atmosphere, or a scene with a compatible time-of-day component. Its preview clock is temporary; it does not save a new scene time. See [Time of day](/docs/guides/time-of-day.md#scene-authoring-and-editor-preview).

## When something looks wrong

| Symptom | First checks |
|---|---|
| Pink material or error cube | Select the actor; read **Asset issues** and Console messages. Confirm the asset exists and cooking succeeded. |
| A source edit has not appeared | Stop Play, wait for the asset cook, and check the Console for errors. |
| An actor is absent | Clear Hierarchy filters; check actor **Active** and render **Visible**, then focus it. |
| Physics does not move | Enter Play. A static body is intentionally stationary; only change its type if the intended gameplay requires it. |
| The Inspector will not edit | Stop Play or cancel a pending Play start, then select an authored actor. |
| An asset cannot be deleted | Read the list of referencing documents; replace or remove those references through the editor. |
| The project cannot open | Share the editor version and the compile splash output, build log or Console diagnostic with the maintainer. |

Use **Project Settings → Packs** to control cooked-art placement. Add explicit asset stems or folders ending in `/` alongside include rules. Right-click an asset or folder in the Asset Browser and choose **Assign to pack…** to open that workflow directly. Select a pack, assign, and inspect **Resolved contents** before Save or Apply. Exact asset assignments override the most specific folder assignment; those override include rules. **Use inherited rules** removes the explicit assignment for that selection.

The preview resolves the unsaved draft through Shinra against the current cooked inventory. Each row explains its placement; **Default pack** shows fallback contents and **Unmatched** exposes assignments with no cooked match. Lists and preview results are paged without dropping members. **Refresh preview** picks up newly cooked assets. Card counts refer to the last cook; scene/prefab, shader and directory/content domains keep their role-based placement.

Use **View → Asset References** to inspect the selected asset’s cooked dependencies or switch off **Cooked** for authoring references. Follow Uses or Used by, expand the chain, and hover for pack placement, size, holds, and the field responsible for an edge. Deferred partition cells are visible without becoming base-scene load requirements. Use **Scene Packs** for the scene’s transitive storage closure.

The selection rail keeps asset identity, cooked size, pack delivery and current store holds visible. Its dependency summary counts unique direct/transitive dependencies, referring assets, missing targets and packs touched. **Cooked size** includes the selection and its unique dependency closure; it is not runtime memory. **Include deferred cells** expands that summary without changing the canvas. Missing targets make the size a known lower bound.

Use **Missing**, **Cross-pack**, **Deferred** and the pack selector to narrow the current graph neighbourhood. Filters combine, retain the selection and connecting paths, and never change the summary totals. Use **Chain** to search beyond direct neighbours. Amber edges cross known pack boundaries; red edges still identify missing targets. **Clear filters** restores the neighbourhood, and **Reveal in Asset Browser** locates the selection’s source.

**Dependencies by cooked size** ranks the complete closure, eight entries per page. Switch between largest and smallest first; unknown sizes stay last. Select a row or **Shift-click** a graph node to pin a **Why is this needed?** explanation without changing the graph focus. It shows one shortest directed chain with reference fields and deferred markers; referrers explain the reverse relationship. **Focus asset** navigates to the traced asset.

**Copy path** copies the displayed logical identity (including the cooked suffix in cooked mode). **Export JSON…** asks for a destination folder and writes a timestamped `asset-dependencies-*.json` report, then displays its path. It includes the selection, the full outgoing dependency closure, sizes, packs, missing targets, provenance and deferred edges according to **Include deferred cells**. Canvas filters, pagination and the 400-node display limit do not restrict the export. Unknown sizes are `null`; sizes describe cooked files, not runtime memory.

## Continue by task

- Build reusable scene objects: [Prefabs](/docs/systems/prefabs.md#create-and-reuse-a-prefab).
- Design a HUD without laying it out in code: [First UI document](/docs/tutorials/first-ui-document.md), steps 1–3; hand slot names and button IDs to a programmer afterward.
- Review or translate interface text: [Localization window](/docs/guides/localization.md#localization-window).
- Tune lighting and atmosphere: [Time of day](/docs/guides/time-of-day.md#scene-authoring-and-editor-preview), [Visual Zones](/docs/systems/visual-zones.md), and [Volumetric media](/docs/systems/volumetric-fog.md#authoring-bounded-smoke).
- Inspect an animated model: [First skeletal animation](/docs/tutorials/first-skeletal-animation.md); ask a programmer to supply the actor and gameplay controls where needed.