llamamod/docs/manual/09-objects.md

# Objects

Objects are everything in a level that *does* something: the llama itself, coins and fruit,
checkpoints, exits, enemies, villagers, moving platforms, cameras, cut-scene triggers and many
invisible helpers. This chapter shows how to find, place, move, turn and configure them, how to
reuse them in other levels and how the editor checks them.

![Placing a coin with the Place tool in the village](img/obj_place.jpg)

## What objects are

In the game's files an object is called a *strat* (short for strategy). Every object has

* a **type** (`Coin`, `CheckPointPost`, `LevelDoor`, `CityGuard` …) – the name of its script,
* a **position** and a **rotation** (only the turn about the vertical axis is used by most types),
* a short list of **parameters** – numbers the script reads when the level starts (for example
  "snap to floor" for a coin or the target chapter of an exit),
* optionally a **waypoint chain** – a list of points the object uses as a path, a camera
  position, a respawn point or the corners of an area (see [Waypoints and paths](10-waypoints.md)).

The script code and the 3D model of each type are stored inside the level file. The editor
never changes them: it copies them from the base level and only edits position, rotation,
parameters and waypoints.

## Which objects you can place

Every level is built on a **base level** (see [Introduction](01-introduction.md)). The object
types of that base level can be placed right away, because their code and model are copied from
it; types of other levels must be imported first (below). The village (Village – Chapter 1, the default base of new levels) has coins,
fruit, checkpoints, exits, villagers, cameras and more; other bases offer other enemies and
gadgets – the river has river logs, the city has guards, and so on.

> **Note:** If a type is missing in your base level, the Objects panel simply does not list it. A
> setup that needs a missing type (for example an exit on a base without `LevelDoor`) tells you so
> in an error message, such as "this base level has no LevelDoor to copy".

To use object types from other worlds, import them from **Assets → All worlds** – see
[Importing objects from other worlds](#importing-objects-from-other-worlds).

## The Objects panel

The **Objects** panel sits in the left dock next to the Outliner – the tab with the ⊙ icon (open it with
**Tools → Object palette** if you closed it). It has three parts: a search row, the
**Quick setups** buttons and the list of all placeable types.

| Element | What it does |
|---|---|
| **Search objects…** | Filters the list by type name and by the description of decoded types |
| Category box | **All categories**, **Player & start**, **Exits**, **Checkpoints**, **Collectibles**, **Cameras**, **Triggers & dialogue**, **Forces & currents**, **Other objects** |
| **★** button | Shows only your favourites |
| Quick setups | One-click helpers, see [One-click setups](#one-click-setups) |
| Type list | Every placeable type with a rendered thumbnail, its category, the number of variants and the marker **parameters decoded** |

### Object list

* **Click** an entry to make it the current type and switch to the **Place objects** tool
  (**P**). Then click in the viewport to place it.
* **Drag** an entry into the viewport to place one object exactly under the mouse pointer.
* **Right-click** an entry for its menu (this does not pick the type or switch tools): **Add to favourites ★** / **Remove from favourites**
  (favourites are marked with ★, listed first and remembered between sessions) and, for your
  own [custom types](22-strats.md), **Edit type…** and **Delete type…**. The same menu (with
  **Place at view centre**) opens on the types in **Assets → Objects**.
* Hover an entry for a tooltip with the description of the type.
* **parameters decoded** means the editor knows the meaning of the type's parameters and shows
  named fields in the Inspector (see [Object parameters](#object-parameters)).
* **n variants** means the base level contains the type with different settings (different
  code entry points). The palette places the first variant; to get another one, duplicate an
  existing object of that variant.

Thumbnails are rendered in the background the first time the panel is shown; until then a
category icon is displayed.

## Objects in the Assets panel

The bottom **Assets** panel also has an **Objects** tab with the same types as large tiles,
filtered by category. Drag a type from there into the viewport to place it under the mouse
pointer. The **Prefabs** tab next to it holds your saved groups of objects
(see [Prefabs](#prefabs)).

![The Objects tab of the Assets panel](img/ui_assets_objects.jpg)

## Place tool (P)

The **Place objects** tool (key **P**) puts objects onto surfaces and moves them along the
ground. It is chosen automatically when you click a type in the Objects panel or a quick setup.

### Placing an object

1. Click a type in the Objects panel (the options bar shows *Placing: Coin* or similar).
2. Move the mouse over the level. The tool finds the surface under the pointer.
3. Click to place. The new object is selected, and the status bar shows its position.

With **Snap to floor** on, the object is put onto the *collision* floor under the pointer, not
just onto the visible surface – so it ends up where the llama can actually reach it. Like the
game, the editor only counts the tiles listed in the grid cell under the point: a floor polygon
that reaches into the cell from a neighbouring tile is ignored there (it is used only when the
cell has no floor at all). With grid
snapping on (**G**), the position snaps to the move step first.

### Moving and turning objects

* **Click and drag an object** to move it along the ground. Its height follows the floor when
  **Snap to floor** is on. Hold **Ctrl** while dragging to invert grid snapping.
* With **Move waypoints along** on, the object's waypoint chain moves with it (a guard keeps
  its patrol path, a camera zone keeps its box).
* The selected object shows a **yellow knob** in front of it. Drag the knob to turn the object;
  the angle snaps to the angle step (Ctrl inverts). A checkpoint's respawn node turns around the
  post with it.
* Each drag is a single undo step.

You can of course also use the general **Move (W)** and **Rotate (E)** tools and the
Inspector – see [Selection and transforming](05-selection.md).

### Place tool options

| Option | Meaning |
|---|---|
| **Yaw: Camera direction** | New objects face the way the camera looks (default) |
| **Yaw: Facing the camera** | New objects face you – handy for characters and signs |
| **Yaw: 0° (+z)** | New objects face the +z direction (south on the grid) |
| **Yaw: Keep type default** | New objects get the rotation stored for the type in the base level |
| **Snap to floor** | Put new and dragged objects onto the collision floor under the cursor |
| **Move waypoints along** | Dragging an object also moves its waypoint chain |
| **Exit target** | Only in *Exit* mode: world and chapter the new exit leads to |

The yaw of new objects also snaps to the angle step while grid snapping is on.

## One-click setups

Some objects only work together with other things: a checkpoint needs a respawn point, an exit
needs a special floor, a secret needs an area. The **Quick setups** buttons of the Objects panel
create the complete set with one click in the viewport.

| Button | Creates |
|---|---|
| **Player start** | Moves the player start (or places a Llama with its camera node) |
| **Checkpoint** | Checkpoint post with its respawn node in front |
| **Exit** | LevelDoor on a 1×1 exit floor (material 16) |
| **Secret** | Secret object with a 3×3 box |
| **Coin line** | Starts the Coin tool in line mode, see [Coin tool (O)](#coin-tool-o) |
| **Coin arc** | Starts the Coin tool in arc mode |

### Player start

The player start is the **Llama** object. A level has exactly one, so the setup **moves** the
existing Llama to the clicked point (and turns it to the chosen yaw) instead of adding a second
one. If the level has no Llama yet, one is placed with a single waypoint 2 cells behind it.

The Llama's waypoints are **start camera positions**: the game uses the first one within 2.5
cells of the llama. Moving the start takes the nearby nodes and the village fly-by trigger along.
See [The start camera](11-cameras-triggers.md#the-start-camera).

> **Tip:** **Level → Play from camera position** (**Shift+F5**) starts a play-test at another
> point without moving the real start – see [Building and play-testing](15-build-play.md).

### Checkpoint

Places a **CheckPointPost** (or **CheckPointBox** if the base has no post) and a respawn node
0.4 cells in front of it, on the floor. When the llama touches the post, the game stores the
node as the respawn point; after losing a life the llama reappears there, facing the node's
direction. Turn the post with its knob and the node turns along.

![Respawning at a placed checkpoint](img/obj_game_checkpoint.jpg)

### Exit

Places a **LevelDoor** in the centre of the clicked grid cell and a 1×1 **Floor** brush with
collision material **16** (exit floor) under it. The door fires only when the llama stands on
material-16 floor *in the door's own grid cell*, which is why both are needed.

Choose where the exit leads in the options bar (**Exit target**) before you click, or later in
the Inspector:

* a world (**1 · Village** … **8 · Lab**, **9 · TestLevel**) and a chapter of that world,
* **World finished → world map (7,7,7)** – the end of a world: the game shows the tally and
  returns to the world map.

> **Engine limit:** Do not use *World finished* in a level that runs as a TestLevel chapter
> (world 9): it would unlock a world 10 that does not exist and the map crashes. Pick a chapter
> instead – the Problems panel warns you.

![An exit door selected in the Inspector with its target level](img/obj_exit_inspector.jpg)

### Secret area

Places a **Secret** object with a waypoint box of 3×3 cells around the clicked point and
switches its *Box area* parameter on. When the llama enters the box, the game shows the secret
message and counts the secret. Resize the box with the
[Zones and triggers tool (J)](11-cameras-triggers.md#the-zones-and-triggers-tool-j).

## Coin tool (O)

The **Coin line / arc** tool (key **O**, or the **Coin line** / **Coin arc** quick setups) places
many coins at once. A live preview shows the coins while you move the mouse; **Esc** cancels
after the first click.

* **Line:** click the start point, then the end point. Coins are placed every *Spacing* cells
  from the start towards the end.
* **Arc / circle:** click the centre, then a point on the circle (this sets the radius and the
  start angle). *Count* coins are spread over *Arc°* degrees; with 360° they form a closed ring.

| Option | Default | Meaning |
|---|---|---|
| **Line** / **Arc / circle** | Line | Shape |
| **Coin** / **Coin5** | Coin | Coin type (Coin5 is worth five) |
| **Spacing** | 0.75 | Distance between coins of a line (0.25–5 cells) |
| **Count** | 12 | Number of coins on an arc (1–128) |
| **Arc°** | 360 | Angle covered by an arc (10–360°) |
| **Height** | 0.3 | Height of the coins above the floor (0–3 cells) |
| **Follow floor** | on | Every coin is put onto the floor below it, then raised by *Height* |

Grid snapping applies to both clicks (Ctrl inverts it). All coins of one line or arc are one
undo step.

![A coin arc around a hill](img/obj_coin_arc.jpg)

## Object parameters

Select an object and the Inspector shows the section **Object parameters** above the general
properties. It is shown when one object or several objects *of the same type* are selected;
changes then apply to all of them.

### Parameter fields

At the top a short description explains the type. For decoded types it ends with
*(decoded, confidence high/medium/low)*:

* **high** – the script was read and the behaviour was seen in the game,
* **medium** – the script was read,
* **low** – only the values of the original levels were compared.

Each parameter is a row with a name, an editor and the raw value in small grey hexadecimal
digits on the right:

| Parameter kind | Editor |
|---|---|
| On/off | Check box (stored as 0 or 1.0) |
| Number, distance | Number field in cells |
| Radius | Number field in cells; the script squares it before comparing. Drag it in the viewport with the [Zones and triggers tool](11-cameras-triggers.md#radius-triggers) |
| Seconds | Number field in seconds (the game counts 30 frames per second) |
| Count, world, chapter | Whole number |
| Choice | Drop-down with the known modes; an unknown value shows as *other: …* |
| Event bit | Number 1–32 (0 = none): a progress flag shared with other objects |
| Raw | Plain number for values whose meaning is unknown |

Hover a row for a tooltip with the parameter number (`p0`, `p1` …), its description, the valid
range, the values used in the original levels and the raw value. Values outside the known range
get an orange warning line below the row.

Types that are **not decoded** show *Parameters of this type are not decoded yet – raw values*,
with one row per parameter (*Parameter 0*, *Parameter 1* …). The tooltips still list the values
the original levels use, which is a good hint what makes sense.

If an object has a different number of parameters than its type reads, a warning line appears
with the button **Reset to defaults**. It sets the parameters back to those of the type in the
base level.

### Exit target

For a **LevelDoor** (and the village's **VillageEndDoor**) the section starts with
**Target level**: a world box and a chapter box, and the line *Leads to: …* that names the
target in words. The options are the same as for the [Exit setup](#exit).

### Waypoint row

At the end of the section a row describes the object's waypoint chain – *No waypoints* or
*Waypoints: 4 nodes · patrol path* – with a short explanation of what the nodes mean for this
type, or how many original objects of the type have a chain. Buttons:

| Button | Action |
|---|---|
| **Create path** / **Edit path** | Switches to the Waypoint tool (**N**) to add and move nodes |
| **Unlink** | The object stops using the chain (the nodes stay in the level) |
| **Delete path** | Deletes the chain's nodes |
| **Link…** | Uses an existing chain: choose its first node from a list |
| **Look through** | Only for cameras: [pilot mode](11-cameras-triggers.md#look-through-camera) |

Details: [Waypoints and paths](10-waypoints.md).

### General properties

Below the plugin sections the Inspector lists the raw properties of every object:

* **Type** – object type, code offset in the level's script block, number of variables and
  slots, type flags and extra memory (read-only information copied from the base level),
* **Transform** – position (x, y, z in cells) and rotation (degrees about x, y and z),
* **Behaviour** – the raw parameter list, the waypoint chain reference and the object flags.

You rarely need these; the named fields above are easier and safer.

## Decoded object types

The editor knows the parameters of these types (the rest show raw values):

| Type | Parameters | Waypoints |
|---|---|---|
| **Coin** | Snap to floor (drops onto the floor at level start, random spin), Falls (keeps floor collision, rests on moving floors), No shadow | – |
| **Coin5** | Snap to floor, Falls | – |
| **Health**, **HealthFull**, **HealthGenerator**, **Wompy** | Snap to floor, Falls (Health also No shadow) | – |
| **Grapes**, **HealthBanana**, **ChargeBooster** | Snap to floor | – |
| **RubyIdol** | Falls, Snap to floor | – |
| **CoinLine** / **CoinCircle** | Coins (count), Spacing / Radius – spawners that create coins at run time | – |
| **Secret** | Box area | 2 nodes: opposite corners of the secret area |
| **Llama** | Helper, Unused, Camera mode | First node = camera start |
| **CheckPointPost** | Collision radius (originals 0.2) | 1 node: respawn position and facing |
| **LevelDoor** | Tribe, World, Chapter of the next level (7,7,7 = world finished) | – |
| **CameraSide**, **CameraLift**, **CameraSetDistance**, **CameraFocusPoint** | see [Cameras and triggers](11-cameras-triggers.md) | box pairs / – |
| **CutSceneCameraDirectional**, **CutSceneTrigger** | see [Cut scenes](11-cameras-triggers.md#cut-scenes) | camera path |
| **ForcePlayerMovement**, **WaterReboundPoints**, **ObjectDontDropInBox**, **FallOffNoHurt**, **RiverCurrentBox** | see [Force and water objects](11-cameras-triggers.md#force-and-water-objects) | points / box |
| **RubyIdolDoor** | Idols needed, Offset (sign distance) | – |
| **PressurePadDoor** | Pad flags (bit field), Door z, Camera, Camera hold | – |
| **CityGuard** (and CityGuardWithRubyIdol, CowGuard, GorillaGuard, LizardGuard, WarthogGuard) | View range, Chase range, Event bit (0 = active at once), Wall collision (CityGuard only) | Walking boxes: node pairs; the guard must **start inside one box** |
| **CowGuardSpawner** | View range and Chase range of its guards, Max guards, Interval (s) | Walking boxes handed to its guards; the spawner must stand inside one |
| **Alligator**, **AlligatorSpawner** | Spawner: Max alligators, Interval (s), Floor collision | Walking boxes: node pairs; an alligator outside every box is moved into the first one; a spawner's alligators walk straight ahead into the first box |
| **JumpingBeetleBlue**, **JumpingBeetle** | Jump time, Wait, Jump height, Pause | Jump targets |
| **Spider** | Range, Speed, Down time, Up time, Start down | Path |
| **Bunny** | Flee range | – |

> **Guards:** a guard walks around inside the boxes of its waypoint pairs and chases the llama
> only inside them. If it does not start inside one of its boxes, or the node count is odd, the
> game removes it when the level starts – it never appears. Placing a guard gives it one 4×4 box
> around itself and Event bit 0; the Inspector shows a warning and a **Box around it** button
> when the boxes are wrong. An **Event bit** above 0 keeps the guard hidden until another object
> with that event number sets the bit: TipoVillage / ChacaVillage (parameter 6), the smash
> statues (parameter 0), LabBigCutscene (1), LabWall (4), LabSlidingDoor (5), GoldIdol (1),
> CityWall (4), Condor (2), RiverCrocGame (1), RiverTriggerBox (0), KidOnCanoe (4), YzmaRiver
> (2, 6), EndGameTriggerBox (0). **Level → Check** notes a guard whose bit no object in the level
> sets. Guards and alligators get their one box however you add them (Place tool, drag from a
> panel, double-click in Assets).

> **Tip:** For pickups, leave **Snap to floor** on: the game then drops the coin onto the floor
> when the level starts, so a coin placed slightly too high still ends up in the right place.

## Duplicating, copying and pasting

* **Edit → Duplicate** (**Ctrl+D**) copies the selection one cell east. Objects keep a copy of
  their waypoint chain, so a duplicated guard gets its own walking boxes.
* **Edit → Copy** / **Paste** (**Ctrl+C** / **Ctrl+V**) work inside the open level.
* **Delete** removes objects; waypoint chains used only by the deleted objects are removed too.

### Copy objects between levels

**Edit → Copy objects (for other levels)** (**Ctrl+Shift+C**) puts the selected objects – with
their waypoint chains – and selected brushes on the system clipboard, relative to their common
centre. Open another level (or another editor) and choose **Edit → Paste objects at view
centre** (**Ctrl+Shift+V**).

Object types are matched **by name and variant** in the target level's base. Types that the
target base does not have are skipped, and a message lists them. Code and models are not
copied – for that, see [Importing objects from other worlds](#importing-objects-from-other-worlds).

## Prefabs

A prefab is a saved group of objects (with their waypoints) and brushes that you can place again
in any level – a checkpoint with coins around it, a guard with its patrol, a small platform with
a secret.

* **Save:** select the objects and brushes, then **Tools → Save selection as prefab…** (or the
  **Save selection as prefab…** button of the Prefabs tab) and enter a name. The prefab is stored
  as `<data folder>/editor/prefabs/<name>.json` with a thumbnail.
* **Place:** open **Assets → Prefabs**. **Double-click** places the prefab at the view centre,
  **drag** places it under the mouse pointer.
* **Delete** removes the selected prefab file (after a confirmation); **Refresh** rereads the
  folder.

The entries show the base level they were made on and how many objects and brushes they hold.
As with copy and paste, object types the target base does not know are skipped.

## Importing objects from other worlds

A project can only place the object types of its base level – unless you **import** types from
other levels. The editor knows every object type of every original level (about 900 types from
33 levels) and can copy a type into your level together with everything it needs: its script
code, models, animations, textures, sounds and texts. A village level can then have spiders from
the jungle, swinging blades from the city or a merry-go-round from the mountain.

![The All worlds tab of the Assets panel](img/xobj_all_worlds_tab.jpg)

### The All worlds tab

**Assets → All worlds** lists the object types of all worlds with thumbnails:

* **Search all worlds…** finds types by name; the boxes filter by **world** (or *Other levels*)
  and by **category** (enemies, collectibles & pickups, platforms, doors & mechanisms,
  characters, animals, effects …).
* **Importable only** hides types that cannot be imported (player starts, cameras and cut-scene
  objects – about 126 of them).
* A **✓** marks types already imported into this level. The tooltip shows the source level, how
  many instances the original has and what the type depends on (sizes, sounds, texts).
* The first time, the editor builds this catalogue from your CD (a few seconds, shown in the
  status bar); it is cached afterwards. **Level → Rebuild object catalogue** scans again.

### Importing and placing

* **Drag** a type into the viewport: it is imported (in the background) and placed at the drop
  point.
* **Double-click** imports it and places it at the view centre.
* The context menu has **Place at view centre**, **Import into the project** (import only) and
  **Import all of** *level*….

Imported types then appear in **Assets → Objects** and the Objects panel like the base level's
own types, and you place more of them as usual. Selected instances show an **Imported object**
section in the Inspector that names the level they come from.

![An imported object placed by drag and drop, with its Inspector section](img/xobj_drag_drop_inspector.jpg)

### Import a whole world

**Level → Import objects of a world…** (**Ctrl+Shift+I**, or **Import world…** in the tab)
imports many types at once: choose a world or a single level, tick the types you want (with
category, source level, size and notes), keep **Skip types the level already has** on and click
**Preview** – the editor merges them in the background and shows exactly what would be added
(code, models, textures, sounds, texts) against the engine limits. **Import** then adds them.

![Importing all objects of a world, with the size preview](img/xobj_import_world_preview.jpg)

### Limits and things to know

| Limit | Value |
|---|---|
| Level memory (code, textures, models, map, texts) | 16 MB – original levels use up to about 7 MB |
| Sound samples | 128 |
| Texture pages | 127 |

The preview and **Check for problems** report these (errors above a limit, warnings near it).

* **Imports are permanent.** An import changes the level's code layout, so it clears the undo
  history and appears as a fixed "Import …" step. It cannot be removed from the project later –
  delete the placed objects instead, or start a new level.
* The project only stores *which* types were imported, never game data, so sharing stays legal
  and small; the receiver's editor and LlamaMod repeat the import from their own CD.
* A type whose code already exists in your level (for example the coin) is shared – it keeps
  your level's model and textures.
* New instances get the parameters of the first instance in the source level; change them in
  **Object parameters**.
* Objects that belong to level geometry (doors in walls, tile swaps, river or roller-coaster
  specials) import fine but only work with matching geometry. Waypoint chains are copied
  relative to the object.

## Object checks

**Level → Check for problems** and every build check the objects. Double-click a message in the
**Problems** panel to select the object.

| Message | What to do |
|---|---|
| Waypoint chain … is not stored in one piece (error) | Run **Tools → Repair waypoint chains** |
| The level has n player start objects | Delete all Llamas but one |
| … has n parameters, Type reads m | Press **Reset to defaults** in Object parameters |
| Out-of-range value (e.g. a chapter that does not exist) | Correct the field marked orange |
| … needs n waypoint(s) / box nodes come in pairs | Add nodes with the Waypoint tool |
| … has no waypoints; all original … objects have a chain | The type probably needs a chain – create one |
| LevelDoor … without exit floor (collision material 16) | Use the Exit setup or paint material 16 under the door ([Collision](06-geometry.md)) |
| … targets (7,7,7) "world finished" in TestLevel | Choose a chapter as target |
| Respawn node is n cells away (info) | Move the checkpoint's node next to the post |

![Object problems listed in the Problems panel](img/obj_problems.jpg)