Custom map authoring

You design a Keyboard Warriors map the same way you'd build a web page: HTML elements, positioned with CSS, tagged with data-kw-* attributes. The baker turns each tagged element into arena geometry — floors you stand on, walls you hide behind, lava you die in, spawns, pickups. The page's own look becomes the map's texture.

This is how the hand-built maps on our site are made. It's entirely optional — ordinary websites are baked automatically without any of this.

• How it works
• The coordinate system
• Size and scale
• Attribute reference
• Node types
• Pickups
• Spawns and teams
• Hazards
• A complete example
• Tips
• Publishing your map
• Testing your map

How it works

A page becomes a map in one of two ways:

• Authored — the page (its <body> or a wrapper) carries data-kw-map. The baker uses your exact data-kw-* geometry at the page's own size. You are in full control: every box, spawn, pickup and hazard is where you put it. This is the mode for hand-built maps.
• Automatic — any other page. The baker reads the page's real layout (headings, images, sections) and derives terraced cover from it. This is what happens when someone turns news.ycombinator.com into an arena.

A single data-kw-map on your root switches the whole page into authored mode. From then on, only tagged elements become geometry — untagged decoration (backgrounds, labels, your title) is drawn into the texture but is not solid.

The coordinate system

Everything is in page pixels, the same numbers you write in CSS left/top/width/height.

• x grows right, y grows down — screen coordinates, exactly as the browser lays the page out.
• A box's footprint is its rendered rectangle (getBoundingClientRect), so normal CSS positioning works: position: absolute; left; top; width; height.
• Height is the third dimension. data-kw-z is how high a box's top sits, and data-kw-extrusion is how thick it is, both on the same scale as page pixels: data-kw-z="72" is as high as 72 px is long. Leave them off and the baker derives heights from nesting, but for a hand-built map you usually set them so you know exactly how tall everything is.
• Point markers (spawns, pickups) use the centre of their element, so a tiny 8×8 div is enough.

CSS border-radius is retained.

Size and scale

The arena is your map's size: the scroll size of the element with data-kw-map (usually <body>). Give it an explicit width and height.

A map larger than the maximum is cut off at 4000 px: the screenshot ends there and boxes that start beyond it are dropped. A smaller one is padded up to the minimum. 1280 px wide is the size of every arena made from a normal web page, so a map that wide plays at the familiar size; wider is a bigger arena.

The scale is fixed: 1 page pixel is always the same size in the game, on every map, hand-built or not. The numbers below hold whatever your map's size.

The player is 31 px tall and 17 px wide. The highest ledge each move reaches, measured from the surface the player stands on, in the units you write in data-kw-z:

The plain jump is measured in the game; the others are worked out from it, so leave some margin.

Heights are capped: data-kw-z from 0 to 600 and data-kw-extrusion from 1 to 400. For a tower taller than 400, stack two boxes with the same footprint: one from the floor up, one on top of it.

Counts a map may have at most:

Attribute reference

Put these on absolutely-positioned elements inside your authored page.

Notes:

• data-kw-z and data-kw-extrusion take a plain number; empty or non-numeric is ignored.
• A page with any data-kw-pickup marks places only those pickups — the automatic random placement is switched off. So if you place one, place them all (including weapons).

Node types

data-kw-node decides how a box behaves underfoot:

data-kw-anchor:

• ground — the box sits on the floor regardless of its z. Use it for the main structures.
• floating — the box stays at its z, with nothing holding it up. Use it for platforms, bridges and islands you reach by jumping.

Pickups

data-kw-pickup="<kind>" on a small marker div places one pickup at its centre.

Placement tips:

• Mirror weapon pickups through the middle so neither team is closer to one.
• Put the strongest pickups (Shield, the Sniper Rifle) somewhere contested — the centre, or a high perch you have to commit to reach.

Spawns and teams

Players pick the mode when they join, and every map plays both. Mark each spawn with data-kw-spawn="some-id" on a small div; the spawn is at its centre, at height data-kw-z. Ids just need to be unique (red-1, blue-3 read well).

So tagging is optional. Without it, teams start at either end of the map. Tag spawns when you want to place each team's base yourself, and tag both sides: with only one side tagged, the automatic split is used.

Spread deathmatch spawns around the whole map; in a small cluster, players respawn on top of each other.

Where exactly a player appears:

• On top of the highest box under the marker, so a spawn marker over a tower puts players on the tower, and data-kw-z is only used where there is no box underneath (keep it above any lava there).
• Markers outside the page are pulled back to its edge.
• No spawn markers at all: the baker places spawns itself, on the highest, largest boxes. That works, but you lose control over where fights start, so mark your own.

Hazards

data-kw-hazard="lava" (or "void") covers the element's whole rectangle with a kill zone. Give it a data-kw-z for where its surface sits and a data-kw-extrusion for thickness. Touch it and you die, so hazards double as the gaps between your platforms — leave open lava under a run of floating islands and the jumps suddenly matter.

A complete example

A compact team-deathmatch arena: two ground towers, a floating bridge between them, lava underneath, a spawn and a pickup per side, and a contested pickup in the middle.

<body data-kw-map style="margin:0;position:relative;width:1280px;height:512px">
  <!-- The lava floor everything sits over -->
  <div data-kw-hazard="lava" data-kw-z="0" data-kw-extrusion="14"
       style="position:absolute;left:0;top:0;width:1280px;height:512px"></div>

  <!-- Red tower (left) and blue tower (right) -->
  <div data-kw-node="solid" data-kw-anchor="ground"
       style="position:absolute;left:57px;top:128px;width:256px;height:256px"></div>
  <div data-kw-node="solid" data-kw-anchor="ground"
       style="position:absolute;left:967px;top:128px;width:256px;height:256px"></div>

  <!-- A floating bridge joining them across the lava -->
  <div data-kw-node="bridge" data-kw-anchor="floating" data-kw-z="50" data-kw-extrusion="13"
       style="position:absolute;left:334px;top:228px;width:612px;height:64px"></div>

  <!-- One spawn per side -->
  <div data-kw-spawn="red-1"  data-kw-spawn-team="red"  data-kw-z="43"
       style="position:absolute;left:164px;top:213px;width:11px;height:11px"></div>
  <div data-kw-spawn="blue-1" data-kw-spawn-team="blue" data-kw-z="43"
       style="position:absolute;left:1095px;top:213px;width:11px;height:11px"></div>

  <!-- A health pack on each tower, mirrored; the Sniper Rifle fought over in the middle -->
  <div data-kw-pickup="health" style="position:absolute;left:185px;top:156px;width:6px;height:6px"></div>
  <div data-kw-pickup="health" style="position:absolute;left:1095px;top:156px;width:6px;height:6px"></div>
  <div data-kw-pickup="sniper" style="position:absolute;left:640px;top:213px;width:6px;height:6px"></div>

  <!-- An editor-only label the bake ignores -->
  <h1 data-kw-ignore>My Arena</h1>
</body>

Our own maps are fuller, styled examples worth reading: open them and view the page source. Facing Tabs builds two towers from real styled panels, with terraced steps, a bridge, spawn clusters and a full pickup spread; Frost Yard is a small symmetric team yard.

Tips

• Build wide and shallow. ~1280×512 plays best; tall maps put spawns far apart.
• Set z and extrusion on everything in a hand-built map, so heights are deliberate rather than derived.
• Keep gaps bot-sized. A running jump clears about 180 px, but bots only jump gaps up to about 80 px. Wider gaps work for people and leave bots stranded (empty seats fight nobody).
• Keep jumps honest. Space floating platforms within the jump heights in Size and scale; High Jump (about twice as high) and Impact Hammer launches are for the hard-to-reach spots.
• Style the elements however you like. Colours, borders, text and images all bake into the texture, so the map looks like the page. Only the data-kw-* tags decide what is solid.
• Place every pickup once you place one — the first data-kw-pickup turns off automatic placement.
• Use data-kw-ignore for anything that should be visible while editing but not part of the arena.

Publishing your map

A map is just a web page, so you publish it by putting it online. Anywhere public works: GitHub Pages, Netlify, your own site.

1. Host your HTML page (with data-kw-map on its root) at a public https:// address.
2. Open it in your browser, click the Keyboard Warriors extension, and press Create.
3. The server bakes your page with your exact geometry. From then on, anyone who opens the extension on that address sees the arena and can join. Share the page's link and people play there.

Players choose Team Deathmatch or Deathmatch when they join; every map supports both (see Spawns and teams).

The bake loads your page the way a visitor would, within limits:

Keep the page self-contained and light: inline styles, a few images, no logins or cookie walls in the way.

Testing your map

You test the same way you publish: with the extension. The quick loop while you're building:

1. Host the page somewhere public (a free static host is fine) and open it.
2. Press Create in the extension, then Start a match and walk your map.
3. Edit the page, and give its address a new query string: …/my-map/?v=2, then ?v=3. An arena belongs to its exact address, so each new address is a fresh bake right away. (Once an address has an arena, the extension offers Join instead of Create, and the arena is rebuilt at most once an hour.) Create allows about 5 bakes per 10 minutes per person, so that's your test pace.
4. When it plays right, share the plain address. That one gets your latest version the next time it's rebuilt.

What to check on each run:

• Tilt view (press T) shows the whole map from above: every box you tagged should be there, at the height you meant.
• Spawns: play both modes; in Team Deathmatch each team should start on its own side.
• Jumps: walk every route you designed against the reach table in Size and scale.
• Bots fill empty seats and use the whole map: if they never reach an area, players probably can't either.