initial commit: llamamod 0.2.0 – reverse-engineered level formats (wad, map, trak, text, stpc), python tools and notes, java mod manager (iso install, mod pipeline with exe patching, save editor, wine/windows launcher) with mods (test world, debug wireframe, mirror, randomizer, fog, cheats, intro skip, practice, free camera, boot to level, level projects) and the 3d level editor (geometry, objects, cross-world import, environment, textures, play-test, manual)

docs/manual/11-cameras-triggers.md

@@ -0,0 +1,200 @@
+# Cameras and triggers
+
+The game has no free camera: it follows the llama on its own, and special objects in the level
+change how it does that – camera zones, focus points and cut scenes. Other invisible objects react
+when the llama enters an area or comes close: secrets, cut-scene triggers, force zones. This
+chapter shows how to see, set up and tune all of them.
+
+![A CameraSide zone with its box and the computed game camera](img/obj_camera_zone.jpg)
+
+## How the game camera works
+
+During play the camera hangs behind the llama at a certain **distance** and **height** and turns
+with it smoothly. Camera objects change these values while the llama is inside their area:
+
+* a **camera zone** sets the height, distance and often a fixed view direction (yaw),
+* a **focus point** turns the camera towards an object when the llama is near,
+* a **cut scene** takes over the camera completely and flies it along a path.
+
+All camera objects are invisible in the game. In the editor they are drawn as markers, their
+areas as boxes and their cameras as frusta (pyramids showing the view).
+
+## The start camera
+
+The **Llama** (the player start) owns a waypoint chain. Its **first node is the camera's start
+position** when the level begins; the game then moves the camera to its normal place behind the
+llama. Levels made with the editor put this node 8 cells behind the llama (the
+[Player start](09-objects.md#player-start) setup keeps it there when you move the start).
+
+The Llama's *Camera mode* parameter switches between the normal and an alternative camera
+behaviour.
+
+> **Note:** In the original levels the Llama's chain is often a longer list used by the level's
+> scripts (for example the village's fly-by at the start). Edit it with care.
+
+## Camera zones
+
+A camera zone is an object with a **box**: two waypoints marking opposite corners on the ground.
+While the llama stands inside the box (the game only tests x and z), the zone controls the camera.
+Edit the box with the [Zones and triggers tool](#the-zones-and-triggers-tool-j).
+
+### CameraSide
+
+The most common camera zone. Its parameters (Inspector → **Object parameters**):
+
+| Parameter | Meaning |
+|---|---|
+| **Height** | Camera height above the llama, 0 = keep the current value |
+| **Distance** | Horizontal distance behind the llama, 0 = keep |
+| **Yaw mode** | **free**; **node yaw** – the camera looks in the direction of the zone's first node; **node yaw ±180°** – that direction or the opposite one, whichever is closer to the current view; mode 3, mode 4 (unknown) |
+| **Height limit** | Only active while the llama is below the first node's height |
+| **Flag 0x10000** | Sets an object flag (purpose unknown) |
+| **Several boxes** | The chain holds several boxes (node pairs 1–2, 3–4 …) |
+| **Height offset** | Added to the camera height |
+| **Alt. height** / **Alt. distance** | Used instead of Height / Distance in a special game state |
+| p5 … p9 | Not decoded (originals use small values) |
+
+With the **Camera frusta** layer on, a selected CameraSide shows where the game camera will be:
+the editor assumes the llama in the centre of the first box (and distance 2, height 1 when the
+parameters are 0).
+
+![Entering the camera zone switches to the high view in the game](img/obj_game_camera_zone.jpg)
+
+> **Tip:** The easiest way to set up a CameraSide is [Look through camera](#look-through-camera):
+> select the zone, press **Ctrl+Shift+L** and fly the viewport to the view you want. Height,
+> distance and the node yaw follow.
+
+### CameraLift
+
+A camera zone for lifts and object-relative views, with one box.
+
+| Parameter | Meaning |
+|---|---|
+| **Yaw source** | **none**, **object yaw** (the camera turns with the zone object) or **player yaw** |
+| **Use helper position** | Tests the box against a helper object instead of the llama |
+| **Smooth** | Softer camera movement |
+| **Height limit** | Only while the llama is below the node's height |
+| **Flag 0x10000**, p2 | Not fully understood |
+
+### CameraSetDistance and CameraFocusPoint
+
+* **CameraSetDistance** sets several camera values while it is active: *Height* and four raw values
+  (*Value g82*, *g68*, *g83*, *g73*) whose exact effect is not known yet.
+* **CameraFocusPoint** turns the camera towards the object while the llama is within **Radius**.
+  Further parameters: *Min. height*, *Max. angle* (largest angle between object and view),
+  *Height limit*, three flags and *Blend* (0–1, how fast the camera turns). The radius can be
+  dragged in the viewport (see [Radius triggers](#radius-triggers)).
+
+## Cut scenes
+
+Cut scenes are made of two kinds of objects:
+
+* **CutSceneTrigger** starts a scene when the llama comes within its **Radius**. Its chain is the
+  camera path. Parameters: *Character* (the trigger is a talking character: drops onto the floor),
+  *Radius*, *Event bit* (the scene is skipped once this progress bit is set – so it plays only
+  once), *Height check* (the llama must also be above the trigger), *Flags* (1 = face the
+  llama, 2 = cannot be skipped) and two flags whose purpose is unknown.
+* **CutSceneCameraDirectional** is the camera of a scene. Every node of its chain is a camera
+  position; the node's **yaw** and **pitch** give the view direction. Parameters: *Event bit*,
+  *Mode*, *Wait*, *Disabled* (removes itself at the start), *End mode*.
+
+The dialogue, animations and character movements of a scene are part of the object scripts and
+cannot be edited – but you can move, re-aim and re-time the camera, move the trigger and change
+its radius.
+
+![Camera frusta of a cut-scene camera path](img/obj_cutscene_frusta.jpg)
+
+## Camera frusta layer
+
+The **Camera frusta** layer (options bar → **Layers**, on by default) draws, for the selected
+objects:
+
+* **CameraSide** / **CameraLift** – the computed game camera looking at the zone,
+* **cut-scene cameras** and **camera nodes** – a frustum at every node, pointing along the
+  node's yaw and pitch.
+
+The game's field of view is approximated with 60°.
+
+## Look through camera
+
+**View → Camera → Look through camera (pilot)** (**Ctrl+Shift+L**), or the **Look through**
+buttons in the Inspector and the options bar of the Zones and triggers tool, turns the viewport
+into the selected camera:
+
+| Selection | The viewport shows | Flying changes |
+|---|---|---|
+| A camera node (any waypoint) | The view from the node | Node position, yaw and pitch |
+| A cut-scene camera or other camera object | The view from the first node of its chain | That node's position, yaw and pitch |
+| A **CameraSide** zone | The game camera of the zone | *Height*, *Distance* and the first node's yaw |
+| A **CameraLift** zone | The game camera of the zone | The first node's yaw |
+
+While pilot mode is on, fly as usual (right mouse button + **W A S D**, **Q / E**) – the camera
+object follows the viewport, and the whole pilot session is **one undo step**. Press
+**Ctrl+Shift+L** again, or select something else, to end it. The status bar shows *Piloting …*
+while it is active.
+
+![Piloting a camera: the viewport is the camera](img/obj_pilot.jpg)
+
+> **Note:** The first node of some original cut-scene cameras is a fly-in start point, so looking
+> through it may show a wall.
+
+## The Zones and triggers tool (J)
+
+The **Zones & triggers** tool (toolbar, key **J**) adds handles to the selected object:
+
+* **pink corner handles** at the four corners of each box of a box zone – drag a corner to resize
+  the box; the opposite corner stays,
+* a **yellow radius knob** for every radius parameter (CutSceneTrigger, CameraFocusPoint, guards'
+  view and chase ranges, ForcePlayerMovement, Bunny) – drag it to change the radius; the status
+  bar shows the value.
+
+Grid snapping applies (Ctrl inverts it). Clicks elsewhere select as usual. The options bar has a
+**Look through camera** button for camera zones. Each drag is one undo step.
+
+![Dragging the corners of a secret area](img/obj_zone_handles.jpg)
+
+### Box zones
+
+These types use one box (two nodes) – or, for CameraSide with *Several boxes*, several pairs:
+
+| Type | Effect while the llama is inside |
+|---|---|
+| **Secret** | Shows the secret message and counts the secret (needs *Box area* on) |
+| **CameraSide**, **CameraLift** | Camera control, see [Camera zones](#camera-zones) |
+| **ObjectDontDropInBox** | Objects (for example fruit from smashed pots) are not dropped here |
+| **FallOffNoHurt** | Falling off costs no energy (optional *Game state* condition) |
+| **RiverCurrentBox** | River current (not decoded in detail) |
+
+The box is a rectangle on the ground; the game ignores the height. The editor draws it with an
+estimated height of about 1.2 cells above the lower node.
+
+### Radius triggers
+
+Radius parameters are distances in cells. The scripts compare the *squared* distance, which the
+editor handles for you – just enter or drag the radius. The **Zone areas & trigger radii** layer
+draws the circles of the selected objects.
+
+![The trigger radius of a cut-scene trigger](img/obj_trigger_radius.jpg)
+
+## Force and water objects
+
+* **ForcePlayerMovement** pushes or steers the llama towards the points of its chain while it is
+  within *Radius*: *Active*, *Radius*, *Game state* (only in that state), *Lock controls*,
+  *Align yaw* (the llama turns to the node's yaw).
+* **WaterReboundPoints** (and **WaterReboundPointsTurnsOff**): the points of its chain are where
+  the llama is thrown back to after falling into water. Parameter *Active*.
+
+## Zone areas layer
+
+The **Zone areas & trigger radii** layer draws the boxes of **all** zone objects as outlines and
+fills the boxes and radius circles of the **selected** ones. Switch it off in a busy original
+level if the outlines get in the way.
+
+## Known limits
+
+* The camera preview of CameraSide assumes the llama in the box centre and the default distance
+  and height when the parameters are 0; the real camera also depends on where the llama enters.
+* Zone heights in the viewport are estimates; the game tests x and z only.
+* Many camera parameters are only partly understood (*p5 … p9*, *Value g…*). Copying values
+  from similar zones in the original levels works best.
+* Cut-scene content (dialogue, animation) cannot be edited.