Building Levels with the Canal Sim Editor

This guide has two halves in one page. The walkthrough (Sections 1–4) builds real levels from scratch, start to finish — read it in order the first time. The reference at the end (the cheat-sheet, the checker, troubleshooting and glossary) is there to jump back to whenever you're stuck. Use the contents list on the left to hop around.

Introduction

The level editor is a web page that lets you design your own canals for Canal Sim and drop them straight into the game. You build a canal by clicking pieces from a palette — a straight here, a bend there, a lock, a moored boat — and a live picture of your canal updates as you go. When you're happy, you Save it as a file and load that file into the game.

There are two ways of working, and the editor has a switch for each:

• Levels Level mode — you build one canal at a time. A stage can hold up to 20 of these levels. This is where you'll start, and it's all of Sections 1–3 below.
• Map Map mode — you draw one big canal network once, then carve a whole stage of missions out of it, each with a different start and finish. That's Section 4.

Why the checker matters most.

At the bottom of the editor there's a live checker that reads your level as you build. Its promise is simple: if the checker is green, the game will build your level. You never have to guess whether something is allowed — the checker tells you, in plain English, the moment it isn't. Half of learning the editor is just learning to read that bar. We'll come back to it again and again.

A couple of habits worth picking up first:

• Everything is measured in feet. Widths, lengths, turning radiuses — all feet.
• Order matters. The canal is built top-to-bottom down the list of pieces, like laying track for a toy train. Move a piece up or down the list and you move that bit of canal.
• Nothing is saved for you. The editor runs entirely in your browser. Use Save often to keep a file on your computer, and Load to pick up where you left off.

Opening the editor

Open kingparamount.github.io/canal-sim-builder in a browser. It works best on a laptop or desktop — you'll want the room.

You can come back to this guide at any time from inside the editor: click the ? button in the top-right of the top bar and it opens in a new tab.

The editor at a glance

Once you're in, the screen has four parts. It's worth knowing their names, because the rest of the guide uses them.

• The palette (far left) — the pieces you can add, split into two tabs: Track (straights, bends, width changes, junctions) and Features (locks, wharves, moored boats, NPC boats, dialogue). Click a piece to add it.
• The preview (middle) — a live, top-down picture of your canal, drawn by the same engine the game uses. The maroon arrow is where the player's boat starts.
• The section list (right) — one card per piece of canal, in order, top to bottom. This is where you set the numbers. It always begins with a Start card and ends with an End card.
• The checker (bottom) — the live status bar. Green means go.

Basic vs Advanced

The Basic / Advanced switch on the top bar hides or shows the trickier tools. Basic is a tidy starting point — it hides junctions, map mode, NPC routing, out-and-back and narrow locks. Flip to Advanced when you want them (Sections 2–4 assume Advanced). Nothing you build in Basic is lost when you switch.

Section 1 · Build your first level

We'll build a complete, simple level end to end: a ribbon of canal with a bend, a squeeze, a warning message and a parked boat to dodge. We'll call it “The Miller's Run” and put it in the tutorial stage, Helmsman School. Follow along in the editor — by the end you'll have made a real, playable level.

1.1 · Name the stage and the level

On the top bar, type a Stage name — Helmsman School. Then, in the Level box next to it, name this first level The Miller's Run. A stage is just a collection of levels that share a name; you can add up to 20 and switch between them with the same Level dropdown.

1.2 · The Start card

Every level opens with a Start card. It sets who's driving and how the canal begins.

• type — how the canal begins. Stank and Stub are two looks for the same thing: a back wall the boat starts just in front of. (Marina and Wharf come later, in Section 2.) Pick Stank.
• boat — the player's boat. There are five, in five lengths: Waterbeetle (30 ft, small and nippy) up to NursingBros (72 ft, long and hard to turn). Longer boats make a level harder. Pick PatBraces (40 ft).
• width — how wide the canal is at the start, in feet. Try 25.
• max hits — how many crashes before the player fails. 5 is fair; 100 effectively means “you can't fail by crashing”, handy while testing.
• zoom — how close the camera starts (higher = closer). 4 is a good default.
• time, ★ 2, ★ 3 — a timer and two bonus-star challenges. Leave these for Section 2; the defaults (Clean run + No speeding) are fine.
• Start dialogue — an optional speech bubble at the very start. Type something in character: Morning! Take her steady down to the mill.

1.3 · Straights and bends

Now lay some track. Make sure the palette's Track tab is selected, then click a piece to add it — it appears as a new card at the bottom of the list, and the preview updates at once.

1. Click Straight. On its card, set length to 60 ft — a run to get going.
2. Click Curve left. Set angle 45° and radius 120 ft — a gentle left-hander. (A smaller radius makes a tighter, harder bend; an angle of 180° is a full U-turn.)

Type any number you like. Every number box accepts any whole number you type — the dropdown of presets is only a quick-pick for common values. Want a 137 ft straight or a 33° bend? Just type it. (A few boxes that the game fixes to a set list — camera zoom, marina berth counts — stay as plain dropdowns.)

1.4 · A squeeze — the width change

A narrow pinch is a classic test of steering. Click Width change and set:

• side — which bank moves: left, right or both. Choose both.
• new width — the width to change to. Type 15 ft — a tight squeeze.
• over — how long the change takes. 30 ft.

Widths don't reset. Once you've narrowed to 15 ft the canal stays 15 ft until you change it again. So after the scary bit, add another Width change (both, back to 25 ft, over 30 ft) to open it out.

1.5 · A pop-up message

Switch the palette to the Features tab and click Dialogue. Type your warning: Mind the squeeze! A dialogue box pauses the boat (and the timer) until the player taps to dismiss it — good for hints, a bit of story, or a joke. Put this one before the squeeze so it warns in time.

(To split one Dialogue card into several bubbles in a row, separate them with a / — e.g. Nearly there. / Mind the squeeze!)

1.6 · A boat to dodge

Click Moored boat and pick a class — a little Waterbeetle. It drops a parked boat against the towpath for the player to squeeze past. The editor makes the section just long enough to hold it. Bumping it hurts exactly like hitting the bank.

1.7 · The End card

At the bottom of the list is the End card. Like Start, its type can be Stank, Stub, Marina or Wharf. Leave it as Stank — the level finishes the moment the player reaches it. (You can add an End dialogue here too, for a closing line.)

1.8 · Read the checker

Glance at the bar along the bottom. If everything's in order it reads:

If something's wrong, the bar turns red and names the problem. For instance, if you add a wharf and leave its name blank:

1.9 · Save it — and get it into the game

Click Save (top right). The editor downloads your whole stage as a single .json file. To play it: open Canal Sim and go to Settings → Bonus Stage, then load that file. Your levels appear as ordinary levels — the game can't tell they were homemade.

Save is the real export. The .json file is your stage. Keep it safe; to carry on editing later, click Load and pick it back up. (There's also a 🗺 Export as PNG button that saves a pretty map picture of your canal — that's just an image to share, not the way into the game.)

1.10 · Worked example — The Miller's Run

Here's the finished level. Notice how the section list reads straight down — Start, then each piece in order, then End — and how the preview mirrors it, with the squeeze pinching in and the moored boat to pass.

Every card has a row of small buttons — drag the ⠿ grip to reorder, use ↑ ↓ to nudge a piece up or down the list, ⧉ to duplicate it, and ✕ to delete it. That's all you need to reshape a level.

Section 2 · Adding detail

Section 1 got a level working. This section adds the things that turn a bare canal into a proper challenge. Flip the top bar to Advanced to see everything.

2.1 · Timers and bonus stars

Back on the Start card:

• time — pick a time limit (or none). The clock doesn't start until the player first moves, pauses during dialogue, but keeps running through locks — so be generous if there's a lock.
• ★ 2 and ★ 3 — two optional challenges. Every level gives one star just for finishing; these earn a second and third. Pick a condition from the dropdown, and for some a number fills in beside it:

Pick a pair that pulls two ways. “Clean run” and “No NPC hits” overlap — win the first and you get the second free. Better to ask for clean and quick, or clean and no reverse, so each star is its own challenge.

2.2 · Wharves

A wharf is a concrete quay along the towpath the player can pull in at. Add one from the Features tab. Its card has:

• name — every wharf needs one (it's how dialogue and stars refer to it). The editor pre-fills a random name; rename it to anything, but don't leave it blank.
• length — how long the quay is.
• must moor — tick this to make stopping here required to finish the level.
• moor message — an optional line shown when the player ties up.

Why wharf names should be simple.

The editor turns the name you type into a tidy lowercase id behind the scenes and builds the sign and the spoken name from it. Plain names (“Stoke”, “Penny Bridge”) work best. You can drop a wharf's name into any message with {wharf:stoke} and the game fills in “Stoke Wharf”.

2.3 · Moving boats (NPCs)

An NPC boat is a second narrowboat that drives itself — coming the other way, or heading off up the canal. Add one from Features, place it where you want it to start, and set:

• boat — its class, any of the five.
• delay — seconds to wait after its trigger before setting off.
• launch when Adv — either level starts (on the player's first move) or player reaches a particular wharf/marina.
• destination Adv — leave as main line for a boat that just cruises towards the start and vanishes, or send it to a wharf/marina, in which case it routes there (even up a side-arm) and disappears when it arrives.

Give NPCs room. Up to five per level, and they must be spaced out (the checker will warn if two are too close). Aim a boat sent to a destination at somewhere out of sight — it vanishes on arrival rather than mooring up neatly.

2.4 · Locks

A lock raises or lowers the boat between two stretches of canal at different heights. Add one from Features and set its direction — up (the boat climbs) or down. The editor builds the whole thing for you: the entry quay, the chamber, and the exit quay. In the text box you can put a landing message (shown as the player moors) and a chamber message (during the cycle), separated by a /.

Tick narrow Adv for a tight single-boat lock instead of the roomy default. Put two or three lock cards right next to each other in the list and the game merges them into a flight, sharing quays between chambers.

A timer keeps ticking through a lock, and one lock cycle takes 20–30 seconds. If your level is timed and has a lock, be generous with the clock.

2.5 · Start and finish anywhere

The Start and End type dropdowns include Wharf as well as Stank/Stub. Choose Wharf and the player begins moored there (Start) or finishes by mooring there (End) — for delivering a parcel or picking up a passenger. A name box appears; fill it in.

2.6 · Marinas

A marina is the third kind of Start/End type: a wide pool fronted by a row of berths you reverse stern-first into. Choose Marina for the Start or End type and you get two boxes: a berths count and a name.

You give a berth count, not a list. Type how many berths the pool has (9 to 12) and the editor fills it for you — always keeping the first and last berth occupied to frame the pool, and leaving empty slots to spawn, moor or finish in. You don't place individual boats. It's a deliberate simplification: it keeps marinas quick to author and impossible to get wrong.

You can mix families freely — start at a marina and finish at a stank, or vice-versa. And an out & back tickbox Adv on a stank/stub start makes the level a there-and-back trip: sail out, wind the boat right around at the far end, and return. Leave enough width out there to turn a boat the length of yours, or the checker will stop you.

Section 3 · Advanced — junctions and side-arms

Most levels are a single ribbon of canal. A junction branches a side-arm off the main line — a spur the player (or a boat) can turn up, travel along, and reverse back out of. You'll find Junction on the Track tab (in Advanced mode).

Add a Junction and its card lets you set which side it leaves from, the angle it leaves at, and the branch's width. Then click Edit branch → to drill into the arm: the section list now shows the branch's own pieces, and a breadcrumb at the top (Main line › right branch) shows where you are. Build the arm just like a mini-canal — straights, bends, a wharf, even a lock — then click Main line in the breadcrumb to come back out.

• A branch has no Start card — the junction mouth is its start.
• A branch must end in a Branch end cap: a stank, a stub, or a marina (a pool at the arm's head).
• You can even open a junction inside a branch — arms within arms, one level deep.

Make your junctions wide. A boat needs room to swing round where the arm meets the main line — a long boat especially. Use a generous angle (70–90° is kind), a decent branch width, and if in doubt fan the main line out with a Width change just before the junction and back in just after. The checker warns about very sharp arms.

Crossings just happen. If you bend a canal far enough that it loops back over its own path, the editor spots it and draws a bridge (same water level) or an aqueduct (if one side has been through a lock) automatically. You don't author it — just leave a straight section on each side where they cross, and check the preview to see it appear.

Section 4 · Map mode

Map mode is a different way of working, worth its own section. Instead of drawing a separate little canal for every level, you draw one big canal network once — a trunk with lots of wharves, marinas and side-arms — and then carve a whole stage of missions out of it. Each mission is the same water with a different start and finish picked out.

Switch it on with Map on the top bar. Map mode is always Advanced, and it works in two steps, shown as tabs: ① Draw map and ② Define missions.

① Draw the map

Drawing the map uses exactly the same palette and cards you already know — you're just building one long, branchy master canal instead of a short level. Give it a Map Title on the top bar. Add wharves and marinas wherever a mission might want to start or finish, and junctions for the side-arms.

The middle preview swaps to a live OS-style map of the whole network — the same map the game draws.

In map mode, marinas are just a berth count and a name — no must-moor, no messages on the master. That's because a wharf or marina on the master is scenery until a mission gives it a job. You set the must-moors and the messages per mission, next.

② Define missions

Click ② Define missions. The right-hand panel becomes a list of missions; click + New mission to add one, and it opens an edit form beside the map so you can see both.

Each mission re-roles the shared master. The form's main choices are:

• Spawn at / Finish at — pick which wharf or marina the player starts and ends at (or leave them as the trunk's own ends). The map redraws the route as you choose.
• Out-and-back — spawn and finish at the same place, sailing out and winding back.
• Must moor at — tick any wharves/marinas the player must stop at along the way, each with its own message.
• NPC boats — this is how the map's moored boats come alive. Tick a Boat N (the numbers from the map) to turn it into moving traffic for this mission, then set its delay, when it launches, and where it heads. Up to five.
• Intro dialogue and Arrival message — the briefing at the start and the line when they moor at the finish.
• Boat, ★★, ★★★, Max hits, Zoom, Time limit — the usual per-level knobs, set per mission.

Edit the master once, and every mission updates. That's the whole point of map mode: twenty missions can share one canal, so fixing a bend fixes it everywhere at once.

Export the stage

Click Save as before. In map mode it bundles the master map and all its missions into one .json file (and bakes the map picture in). Load it in the game via Settings → Bonus Stage, exactly like a level-mode stage — the missions show up as ordinary levels.

The checker, in full

The bar along the bottom is your safety net. It reads the level live and reports in three states:

• Green — “Level builds — good to go.” The game will accept it as drawn.
• Red — “This level won't build yet.” One or more hard problems. These block Save. Each is listed in plain English; hover it for the full reason and a suggested fix.
• Amber — “Builds, with notes to check.” Soft advice — it'll build, but the note is worth a look (a very sharp junction, boats a bit close, and so on).

Trust the checker over this guide. It runs the exact same rules the game uses when it imports your file. If the checker is happy, the game will be too — so build boldly and let the bar catch you.

Cheat-sheet

Palette — Track tab

Palette — Features tab

Start / End types

Dialogue name tokens

In any message: {wharf:stoke} → “Stoke Wharf”, {marina:home} → “Home Marina”. The name comes from the place's own id, so the sign and the spoken line always match.

Honest limits

A few things the game's oldest hand-built levels can do that the editor deliberately doesn't — so you don't go hunting for a control that isn't there. None of these is a bug; each keeps the tool simpler and its checker trustworthy.

• Marinas are a berth count, not a hand-placed list. You can't pick which berths are full or name individual moored boats in a marina (in level mode). The pool is filled for you.
• Wharf and marina names become lowercase ids. Author names in plain lowercase to avoid surprises with {wharf:...} tokens.
• Some rare tricks aren't offered — spawning a boat facing backwards, a moor-message on an out-and-back marina, a lock with more than two messages. They're unused by real levels; if you ever need one, that's a feature request.

Troubleshooting

The checker is red and I don't understand why

Hover the red item — the tooltip gives the full problem and a suggested fix. The most common ones: a blank wharf/marina name, an out-and-back with nowhere wide enough to turn, two NPC boats too close together, or a junction that's too sharp or empty.

My mission's boat numbers don't match what I expected

“Boat 1, Boat 2…” are numbered in the order they appear along the master canal. Add or remove a moored boat on the master and the numbering shifts — re-check your mission's NPC tickboxes after editing the map.

Save does nothing / won't download

A red checker blocks Save. Fix the listed problems first. If the bar is green and it still won't save, check your browser hasn't blocked the download.

I loaded a file and something looks off

Use Load only on .json files this editor saved. Loading shows a note if it had to adjust anything. The one built-in stage the editor can't re-open is the original Blue Princess JSON (it has no editor data baked in) — but a stage you saved always reloads.

Glossary