hology-game-engine

Files (12)

• SKILL.md
• actors-and-components.md · references/
• ai-and-navigation.md · references/
• animation.md · references/
• input.md · references/
• physics.md · references/
• services-world-assets.md · references/
• shaders-and-vfx.md · references/
• ui-and-react.md · references/
• actor.ts · templates/
• component.ts · templates/
• service.ts · templates/

SKILL.md (first lines)

# Hology Game Engine

Hology is a web-based 3D game engine built on **Three.js**. Games are written in **TypeScript** and run in the browser. It ships a 3D editor plus a gameplay framework with dependency injection, an actor/component model, physics, input, assets, animation, AI and camera helpers.

This file is the always-loaded core: the golden rule, project structure, the essential concepts, and do's & don'ts. **For any topic you touch in depth, open the matching file in `references/`** (see the index below) — that's where the full API and examples live.

Docs: https://docs.hology.app (append `.md` to any page URL for markdown; full index at https://docs.hology.app/llms.txt).

## The golden rule: use Hology's framework, don't rebuild it in Three.js

Hology already wraps most of what a game needs. **Do not hand-roll from scratch in Three.js what Hology provides.** Reach for the framework helper first:

| Need | Use Hology helper — NOT raw Three.js |
| --- | --- |
| A game object | `@Actor()` + `BaseActor` (not a bare `THREE.Object3D`) |
| Mesh + physics body | `MeshComponent` + `PhysicalShapeMesh` (not manual `THREE.Mesh` + external physics) |
| Loading models/textures/audio/materials | Prefer `AssetLoader` for Hology-managed/editor assets and supported paths. Use a direct Three.js loader only for an unsupported format, loader-specific behavior `AssetLoader` does not expose, or an established project pattern. |
| The camera / render loop / pause | `ViewController` (not your own `PerspectiveCamera` + `requestAnimationFrame`) |
| Spawning/finding objects, directional light | `World` (not `scene.add`) |
| Keyboard/mouse input | `InputService` (not raw `addEventListener('keydown')`) |
| Character walking/jumping | `CharacterMovementComponent` (not custom kinematics) |
| Third-person camera follow | `ThirdPersonCameraComponent` |
| Collisions, forces, raycasts | `PhysicsSystem` |
| Overlap zones | `TriggerVolumeComponent` / `TriggerVolume` |
| NPC pathfinding / decisions | `Navigation` + navmesh, behavior-tree nodes (not custom A*/state machines) |
| Character animation blending | `CharacterAnimationComponent` + `AnimationStateMachine` |
| Custom materials / vertex effects | `NodeShaderMaterial` (TS shaders), VFX tooling |
| Shared/global state & systems | `@Service()` singletons |
| Per-frame logic | actor `onUpdate`/`onLateUpdate` or `ViewController.onLateUpdate` (not your own loop) |

Raw Three.js is still fair game for **content details** — geometries, materials, `THREE.Vector3` math, `THREE.Audio` config — but the game's structure, lifecycle and systems should go through Hology. Asset loading should also use Hology's pipeline by default; direct Three.js loaders are narrow exceptions, not a replacement for `AssetLoader`.

## Reference index — open the file for your task

`SKILL.md` covers the essentials. When working on a topic in depth, read the matching file first (they hold the full API surface, options, and worked examples):

| Working on… | Open |
| --- | --- |
| Actor/component classes, lifecycle bugs, `@Parameter`, `MeshComponent`, spawning/moving, prefabs | `references/actors-and-components.md` |
| Services, `GameInstance`, `World`, `ViewController`, `AssetLoader`, `PointerEvents`, sound | `references/services-world-assets.md` |
| Player controls, keybinds, `AxisInput`/`ActionInput`, player controllers | `references/input.md` |
| Physics bodies, collision shapes, collision/overlap events, forces, ray casts, triggers, character movement | `references/physics.md` |
| Playing clips, `CharacterAnimationComponent`, animation state machines | `references/animation.md` |
| NPC AI, navmeshes, `Navigation`, behavior trees, `CharacterMoveToNode` | `references/ai-and-navigation.md` |
| Custom shaders / materials, particle & visual effects | `references/shaders-and-vfx.md` |
| HUD/menus, `HologyScene`, React hooks, signals, overlay CSS | `references/ui-and-react.md` |

Starter files to copy from: `templates/actor.ts`, `templates/component.ts`, `templates/service.ts`.

The public Hology docs do not document networking. Do not invent or rely on multiplayer APIs unless the installed `@hology/core` types/version and the project's requirements confirm them; do not treat exposed networking APIs as stable or generally supported.

## Project structure & entry point

A Hology project is a Vite + TypeScript web app. `hology.config.json` at the root declares the engine paths — keep to these conventions:

```json
{
  "dataPath": "public/data",
  "shadersPath": "src/shaders",
  "actorsPath": "src/actors",
  "componentsPath": "src/components"
}
```

Canonical layout (matches the official `starter-third-person-shooter`):

```
my-game/
├── hology.config.json              # engine paths (above)
├── index.html
├── vite.config.ts
├── tsconfig.json
├── package.json
├── src/
│   ├── main.tsx                    # React bootstrap: renders <App />
│   ├── App.tsx                     # renders <HologyScene> with HUD / menu DOM layered over the game
│   ├── App.css
│   ├── actors/
│   │   ├── index.ts                # default-exported actor registry object for editor/serialized content
│   │   └── *-actor.ts              # one file per actor class
│   ├── components/
│   │   ├── index.ts                # default-exported component registry object
│   │   └── *-component.ts
│   ├── services/
│   │   ├── game.ts                 # GameInstance entry point (see below)
│   │   └── player-controller.ts    # input/keybind service, other game systems & state
│   └── shaders/
│       └── index.ts                # default-exported shader registry object
└── public/
    ├── data/                       # engine data written by the editor — don't hand-edit
    │   ├── asset/
    │   ├── scene/
    │   └── scene-blob/
    └── assets/                     # raw model/texture/audio source files
```

- The entry point is a `@Service()` class extending **`GameInstance`** (conventionally `src/services/game.ts`), referenced by the UI via `<HologyScene gameClass={Game} .../>`. Pass the default-exported actor and shader registry objects to `HologyScene`, plus the component registry when the project defines custom components. These registries make registered classes available when loading editor-authored content. Its `async onStart()` runs when the game starts — spawn actors and wire up controllers/cameras here.
- Add actors that need editor placement or loading from serialized scene/prefab content to the default registry object in `actors/index.ts`. An actor used only through direct runtime spawning with its class does not need to be in that registry. Likewise, add custom components and shaders to their default registry objects when serialized or editor-authored content needs them; adding a class to a registry is distinct from a normal TypeScript import or named re-export.
- Prefer the editor's "Add new → Actor class" to scaffold new actors (it wires up the file + export for you).
- Run in dev with `npm run dev` (Vite, serves on http://localhost:5173).
- Reference: no single "project structure" doc page exists — the canonical example is https://github.com/hologyengine/starter-third-person-shooter (described at https://docs.hology.app/getting-started/starter-project-third-person-shooter.md).
- This React organization matches the official starter, but it is not an engine requirement. Equivalent composition is valid as long as `HologyScene` receives the required game class and registries.

Registry index files default-export an object of classes; do not replace this with named re-exports:

```typescript
// src/actors/index.ts
import ExampleActor from './example-actor'

export default {
  ExampleActor,
}
```

Use the same shape for `src/components/index.ts` and `src/shaders/index.ts`, containing component and shader classes respectively. Import those default objects and pass them to the corresponding `HologyScene` props.

```typescript
// src/services/game.ts — entry point
import { GameInstance, Service, World, inject } from '@hology/core/gameplay'

From KFlamsted/agent-workflow-kit, MIT.

More from KFlamsted/agent-workflow-kit