# Making maps for BUNNY-HOP

> BUNNY-HOP isn't released yet, so details here may still change.

BUNNY-HOP maps are made in **TrenchBroom**, a free map editor made by other people. It opens in its own window next to the game. You build in TrenchBroom, save, and your map appears in the game, ready to play.

You don't need to know Godot, and there's nothing to compile. The game has a shorter version of this guide: choose **Map editor**, then **How to make maps**.

## Getting started

1. In the game's main menu, choose **Map editor**.
2. Press **New map**. If you don't have TrenchBroom yet, the game offers to download it from TrenchBroom's official GitHub page, about 50 MB. Nothing downloads until you agree.
3. TrenchBroom opens with a small starter map: a start, one platform and a finish.
4. Back in the game, press **Play** next to your map to try it.

Everything else is changing that starter map, saving, and playing it again.

Already have TrenchBroom? The game finds it in the usual place and uses it, with no download. Either way, the game adds BUNNY-HOP to TrenchBroom's list of games, and doesn't change anything else you've set up there.

## Learning TrenchBroom

To learn how to move around, draw brushes and use the editor's tools, read [TrenchBroom's manual](https://trenchbroom.github.io/manual/latest), which is also under its Help menu and linked from the game's Map editor page. This guide only covers what's special about BUNNY-HOP.

## Building a course

Everything solid is a **brush**: a simple block you draw with the mouse.

### Materials

Choose a material in the **Face** tab before drawing. A brush with no material won't load in the game.

| Material | Colour |
|---|---|
| `tutorial_grey` | Light grey |
| `tutorial_orange` | Orange |
| `tutorial_wall` | Darker orange |
| `tutorial_yellow` | Yellow |

These are all you can use for now. Your own images are planned, and the game refuses a map with any other material.

The game draws its grid over these itself, so it lines up across brushes whatever you do with their textures in TrenchBroom.

### Tagging platforms

A course needs a start and a finish. To tag a platform, select its brush, right click it, and choose from the menu:

| Tag | What it does | How many |
|---|---|---|
| `bhop_start` | Where the run starts. The timer starts as you leave it | Exactly one |
| `bhop_finish` | Where the run ends | Exactly one |
| `bhop_checkpoint` | Starts a new stage, and is where you come back to after falling | Any |
| `bhop_limited` | A platform you can't stand on for long, so you have to keep hopping | Any |

Tagged platforms show as see-through in TrenchBroom. That's only in the editor, and they look solid in the game.

Each tag must be on **exactly one brush**, and the top of that brush must be a **flat rectangle**.

### Spawn and timer zones

A start platform is the spawn point and the start of the timer in one. To place these separately, such as a run-up room before the timer starts, or a finish line you pass through without landing:

| Flag | What it does | How to add it |
|---|---|---|
| `bhop_spawn` | Where the player appears, and where they come back to before the first checkpoint | Right click an empty spot and add it as an entity. Its box is the size of the player, with their feet at the bottom |
| `bhop_timer_start` | An invisible box with no collision. The timer starts when you leave it | Tag a brush, like a platform |
| `bhop_timer_end` | An invisible box with no collision. The timer stops when you enter it | Tag a brush, like a platform |

A map can have one of each. It needs somewhere to appear (`bhop_start` or `bhop_spawn`), a timer start (`bhop_start` or `bhop_timer_start`) and a timer end (`bhop_finish` or `bhop_timer_end`). If a map has both kinds, the flag is used instead of the platform for that job.

- **Size:** timer zones must be plain boxes at least 64 units in every direction. The timer checks the player's position once per tick, so a thinner line could be skipped at high speed.
- **Height:** the timer follows the player's feet, so make zones tall enough to catch someone jumping through.
- **Speed limit:** speed is limited to 290 units a second inside the start zone, so nobody can enter a run already at full speed. Build run-ups with this in mind.

### Teleports and fail zones

| Flag | What it does | How to add it |
|---|---|---|
| `bhop_teleport` | An invisible box with no collision. Touching it sends the player to a destination, facing its way. They keep their speed, turned the way they now face, unless `keep_speed` is `0`, which stops them like Source | Tag a brush, and set `target` to a destination's `targetname` |
| `bhop_destination` | Where a teleport sends the player, or where they appear at a start or checkpoint that names it | Right click an empty spot and add it as an entity, with a `targetname`. Its box is the size of the player |
| `bhop_fail` | An invisible box with no collision. Touching it sends the player back to their last checkpoint, and counts as a fall | Tag a brush, such as a thin floor under a stage |

Both work like Source's `trigger_teleport`, and they catch a player who passes through within a tick, so they can be thin. Each is one brush, and the box around a brush that isn't square counts.
- **Material:** the brush still needs one of the materials above, but it never shows in the game.

### Settings

Select a tagged brush and open the **Entity** tab:

| Setting | On | Meaning |
|---|---|---|
| `angle` | `bhop_start`, `bhop_checkpoint` | The direction the player faces, in degrees. It must run along one side of the platform. 0 faces along the red axis and 90 along the green one |
| `target` | `bhop_start`, `bhop_checkpoint` | Optional. The `targetname` of a `bhop_destination`. Players appear there, facing its `angle`, which can be any direction, rather than in the middle of the platform |
| `order` | `bhop_checkpoint` | Where it comes in the course: 1, 2, 3 and so on. Each must be different |
| `stage_name` | `bhop_checkpoint` | The name shown for the stage it starts |

With nothing selected, the Entity tab shows the settings for the whole map:

| Setting | Meaning |
|---|---|
| `map_name` | The map's name, also shown for its first stage |
| `map_author` | Who made it |
| `limited_seconds` | How long a player can stand on a `bhop_limited` platform. The default is 2 |

## Making it play well

Some habits from years of bhop maps in Counter-Strike, with the distances measured in this game:

- **Make landings easy to read.** Give the platforms players land on a different colour from the floor, walls and everything else. Players judge each jump at speed, and a course where everything looks alike is hard to read.
- **Let players restart from standing.** After a fall, players start again from a standstill at the checkpoint or destination. A perfect jump from a walk clears about **196 units** between edges, or **212** crouching in the air. Keep the first gap after a checkpoint, destination or spawn to about **160 units**, so it doesn't take a perfect jump.
- **Start easy, then keep the rhythm.** Easy early stages let good players build speed. After that, a sudden wall, a tight turn or a stop breaks their run.
- **Leave room for routes.** Blocks off the main line, which a run doesn't need, give good players faster lines and skips while the main line stays easy.
- **Avoid big empty rooms.** They feel aimless. Letting players see later parts of the course makes it feel connected.
- **Keep fail zones back from edges.** A `bhop_fail` zone next to a platform's edge, or reaching up past its top, can catch a player who only just made the landing. Keep it a little back and below the top.
- **Lay out the platforms first.** Build the jumps and play them before adding walls and decoration, so changing a jump costs nothing. Use **Test from here** at each checkpoint, because that's where players restart.

## Testing your map

**Save to reload.** Save in TrenchBroom (Ctrl+S, or Cmd+S on a Mac) while your map is being played, and the game reloads it within about half a second. You carry on from where you were, and the screen shows **Map reloaded**.

**Test from here.** To try one jump without replaying the map, point TrenchBroom's camera at the spot, then:

1. Choose **Run > Compile Map**, select **Test from here**, and press **Compile**. Nothing really gets compiled.
2. The game puts you at the camera, facing the same way. You don't have to save first.
3. Falling off brings you back to this spot, so you can keep trying.
4. Press the key to start over when you want a real timed run from the start.

After the first time, use **Run > Re-run "Test from here"**. You can give it a key in TrenchBroom's preferences. It reopens the Compile window each time, so close that when you go back to building.

You'll drop from the camera's height, so keep it just above where you want to land. On Windows the game may not be able to come to the front by itself, so you may need to switch to it.

### If something's wrong

A map with a mistake won't load. If you're already playing it, the last good version keeps running and the problem shows on screen. The game names the line of the file where it can.

| The game says | What to do |
|---|---|
| This map needs a … or a … | Add one of the two it names, as a tag or a flag |
| This map can only have one … | Remove the extra one |
| This map has nothing to stand on | Add at least one solid brush that isn't a timer zone |
| A timer zone must be a plain box at least 64 units wide | Make the box bigger, or undo any shaping |
| A bhop_… must be exactly one brush | Keep one brush in that tag, and put the rest in the map as plain brushes |
| This brush has a face with no material | Select the brush and click a material in the Face tab |
| '…' isn't one of the game's materials | Use a material from the list above. This also happens with a map copied from another game |
| '…' isn't something the game knows | Check the spelling of the tag. Only the `bhop_` tags work |
| The top of this platform must be a flat rectangle | Tags work on rectangular tops only. Use a plain brush for other shapes |
| This platform must face along one of its sides | Change `angle` to run along one side of the platform |
| Two checkpoints have the same order | Give each checkpoint a different `order` |
| This checkpoint's target isn't the name of a bhop_destination | Check the spelling, or add a `bhop_destination` with that `targetname` |
| This brush is too far from the middle of the map | Move it inside the map limit, shown as bounds in TrenchBroom's 2D views |
| This brush has no proper shape | A brush has become flat or inside out. Delete it and draw it again |

## Publishing to the Workshop

Steam must be running. Press **Publish** on your map in the Map editor page. Before the form opens, the game checks:

- **The map loads** with no problems.
- **You've finished a timed run on this version,** in either hopping mode. A run from Test from here doesn't count, because it doesn't start at the start. Saving makes a new version, so finish it again after changes.
- **It has a picture.** Press the **Take map picture** key (P, unless you've changed it in Settings) while playing the map. The HUD and your arms are left out, and the picture is saved beside the map as a `.jpg`. Take another to replace it.
- **It isn't a test map imported from another game,** and has no Test from here spot saved in it.
- **Your copy of the game can upload.** Steam doesn't allow it from Family Sharing or a free weekend.

Then fill in the title (it starts as your `map_name`), a description, a difficulty and who can see it: **Public**, **Friends only** or **Hidden**. Tick the box to confirm you made the map or have permission to share it.

Only your `.map` file goes up, exactly as you saved it, with the picture shown on its Workshop page. Steam may ask you to accept its Workshop agreement the first time, and opens the page for it. Your map stays hidden from others until you do.

**Updating:** once a map is on the Workshop, its button says **Update**, and the list shows **Changes not published** after you save. Updating asks what changed, which shows on the Workshop page. Best times belong to one version of a map, so they start again with each update.

**Removing:** **Remove from Workshop** takes it off Steam after asking. Your own file stays. The game remembers the map's Workshop number by where the map is saved, so keep the map in the same place under the same name, or the next publish makes a new item.

## Good to know

- **Falling:** going 256 units below your lowest brush sends you back to the last checkpoint.
- **Size:** the player is 32 units wide, and walks at 250 units a second. Brushes can be up to 16,256 units from the middle of the map, and a map can have up to 10,000 brushes.
- **Layers:** a layer marked "Omit from export" stays out of the game, which is useful for notes or unfinished parts.
- **Groups:** groups and linked groups are fine, and handy for repeating a section.
- **Times:** only a run from the start is timed. Your best time is kept for each version of a map, so changing the map starts it again.
- **Leaderboards:** times on your own maps stay on your computer, and never reach the game's official leaderboards.
- **Achievements:** your own maps don't count towards them.

## Where your maps are

Press **Open maps folder** in the game. Each map is one `.map` file, which you can copy or back up, with its picture and Workshop number beside it once you have them. The `playtest` folder inside is what Test from here writes to, and is safe to delete.