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/10-waypoints.md

@@ -0,0 +1,164 @@
+# Waypoints and paths
+
+Many objects need positions besides their own: a guard walks along a patrol path, a camera zone
+covers a box, a checkpoint stores where the llama respawns, a cut scene flies its camera along a
+route. The game stores all of these as **waypoints** – points linked into **chains**. This
+chapter explains how chains work and how to edit them with the **Waypoint paths** tool.
+
+![A patrol path of a jumping beetle in a new level](img/obj_beetle_path.jpg)
+
+## What waypoint chains are
+
+A waypoint (also called a *node*) has a position, a turn (yaw) and a tilt (pitch), plus a few
+fields whose meaning is not known yet. Every node can point to a **next** node; following these
+links from a first node gives a chain. An object refers to the **first node** of its chain.
+
+* One object uses at most one chain.
+* Several objects may share one chain (the original levels do this in places).
+* A chain without an object is allowed but does nothing.
+
+In the Outliner the chains are listed under **Waypoint chains**. In the viewport nodes are drawn
+as small markers joined by lines.
+
+## Chain roles
+
+What the nodes mean depends on the object type. The Inspector names the role in the
+[waypoint row](09-objects.md#waypoint-row) and in the Waypoint chain section:
+
+| Role | Used by | Meaning of the nodes |
+|---|---|---|
+| **patrol path** | CityGuard, JumpingBeetleBlue, Spider … | Points the character walks or jumps to; patrols wrap from the last node back to the first |
+| **camera positions** | Llama (first node), cut-scene cameras, CutSceneTrigger | Camera position; node yaw and pitch give the view direction |
+| **respawn point** | CheckPointPost | Where the llama reappears, and which way it faces |
+| **box area (two opposite corners)** | Secret, CameraSide, CameraLift, ObjectDontDropInBox, FallOffNoHurt … | Two nodes span a rectangle on the ground (x and z only); some types use several pairs |
+| **point list** | ForcePlayerMovement, WaterReboundPoints | Target points |
+| **waypoint chain** | other types | Meaning unknown – keep the original layout |
+
+For types that are not decoded, the editor guesses: camera objects get *camera positions*, types
+whose originals always have exactly two nodes get *box area*.
+
+## Showing waypoints
+
+By default the viewport shows only the chains of the **selected** objects and nodes – a big level
+has hundreds of nodes. To see all of them:
+
+* **View → Show waypoints of all objects**, or
+* the **Show all chains** button of the Waypoint tool (it toggles the same setting).
+
+Two layers (options bar → **Layers**) control the drawing:
+
+* **Waypoints** – the node markers and connecting lines,
+* **Path directions** – arrows along the chain, a dashed segment from the last back to the first
+  node for patrol paths (they wrap) and a short tick at each node showing its yaw.
+
+Click a node marker to select the node. Hidden or locked objects' nodes are not pickable.
+
+## Waypoint tool (N)
+
+The **Waypoint paths** button of the toolbar or key **N** starts the tool. It edits the chain of
+the **selected object**, or the chain the **selected node** belongs to. The options bar reminds
+you of the mouse actions: *Click: add node · Ctrl+click: insert before · drag: move ·
+Backspace/Del: remove*.
+
+### Adding nodes
+
+1. Select the object (click it while the tool is active – clicking an object selects it).
+2. **Click** on the ground. The new node is added **after the selected node**, or at the end of
+   the chain if the object itself is selected. If the object has no chain yet, the click creates
+   one with this first node.
+3. Keep clicking to add more nodes; each new node becomes the selected one, so the chain grows in
+   the order you click.
+
+**Ctrl+click** inserts the new node **before** the selected node instead (before the first node
+if the first one is selected).
+
+The new node copies the pitch and the unknown raw fields of the last node of the chain. With **Follow
+floor** on it sits on the floor under the pointer; grid snapping applies (Ctrl inverts it – note
+that Ctrl+click therefore also inverts snapping).
+
+### Moving and deleting nodes
+
+* **Drag a node** to move it. With **Follow floor** on it keeps its height above the floor as you
+  drag over hills and steps. Each drag is one undo step.
+* **Backspace** (while the tool is active) or **Delete** / **Edit → Delete** removes the selected
+  nodes and **relinks** the chain: the previous node now leads to the following one. The next
+  node becomes selected, so you can delete several in a row.
+* Moving the owner object with the Place tool moves the whole chain along (option
+  *Move waypoints along*).
+
+### Waypoint tool options
+
+| Option | Meaning |
+|---|---|
+| **Follow floor** | New and dragged nodes stay on the collision floor (on by default) |
+| **Orient new nodes** | A new node faces away from the previous node, i.e. along the path (on by default) |
+| **Reverse** | Reverses the order of the chain; the object then starts at the former last node |
+| **Show all chains** | Toggles between the chains of the selection and all chains |
+
+![Drawing a path for a new object](img/obj_newlevel_path.jpg)
+
+## Waypoint chain section
+
+When a single node is selected, the Inspector shows the section **Waypoint chain**:
+
+* *Node i of n*, the object(s) using the chain and its role – or *not used by an object*,
+* **Select object** – selects the owner,
+* **Edit path** – switches to the Waypoint tool,
+* **◀** / **▶** – select the previous / next node,
+* **Delete node** – removes this node and relinks the chain,
+* **Look through** – shows the view from this node (camera nodes, see
+  [Look through camera](11-cameras-triggers.md#look-through-camera)).
+
+The node's position, yaw, pitch and raw fields are in the general properties below.
+
+## Linking chains to objects
+
+The waypoint row of **Object parameters** (see [Objects](09-objects.md#waypoint-row)) connects
+chains and objects:
+
+* **Create path** / **Edit path** – start the Waypoint tool for this object.
+* **Unlink** – the object no longer uses its chain; the nodes stay in the level (for example to
+  give them to another object).
+* **Delete path** – removes the chain's nodes.
+* **Link…** – opens *Link <type> to a waypoint chain* with all chains of the level, nearest first:
+  first node id, number of nodes, distance from the object and which objects use it (or
+  *unused*). Choose one and press OK.
+
+**Edit → Duplicate** gives the copy its own copy of the chain. Deleting an object also deletes
+chains that no other object uses.
+
+## Chains must be stored in one piece
+
+The game does not really follow the *next* links when it loads a level: it links node number *i*
+to node *i + 1* in the level's node list whenever *next* is set. A chain therefore has to be
+stored **contiguously** – all its nodes one after the other.
+
+The editor keeps chains contiguous when you add, insert or delete nodes. Older projects or unusual
+edits can break this; then **Level → Check for problems** reports an error *Waypoint chain at … is
+not stored in one piece*, and building is blocked. Run **Tools → Repair waypoint chains** – it
+reorders the node list so every chain is in one piece (the status bar says *Waypoint chains repaired*, or *All waypoint chains are stored in one piece*
+when nothing had to be done).
+
+## Example: a patrolling enemy
+
+1. Click **JumpingBeetleBlue** (or another enemy with a patrol path) in the Objects panel and
+   place it with the Place tool.
+2. Press **N**. The beetle stays selected.
+3. Click four points around the area the beetle should cover. Watch the arrows: the dashed
+   segment closes the loop back to the first node.
+4. Press **F5** to try it: the beetle jumps from node to node.
+
+![The beetle jumping along its path in the game](img/obj_game_patrol.jpg)
+
+## Waypoint checks
+
+The Problems panel reports:
+
+| Message | Meaning |
+|---|---|
+| Chain not stored in one piece (error) | Run **Tools → Repair waypoint chains** |
+| … needs n waypoint(s) (…), has m | The type reads more nodes than the chain has |
+| … uses only n waypoint(s), the chain has m (info) | Extra nodes are ignored by the game |
+| … box nodes come in pairs | Box zones need an even number of nodes |
+| … has no waypoints; all original … objects have a chain | Most likely the type needs one |
+| Respawn node is n cells away (info) | A checkpoint's respawn point far from the post |