A step-by-step ordering from Rogueima I MVP-4 toward something with NetWhack's shape. Each step is meant to be finishable on its own, and to leave the game playable when it lands.

For the reasoning behind the grouping, see the roadmap in programs/rogueima/ROADMAP.md. This page is the working list.

move_left, move_down, move_up and move_right are four near-identical routines, each with its own edge check, its own is_walkable call and its own store. Replace them with a single

try_move  ; CL = dx, DL = dy

that computes the destination, bounds-checks it, asks is_walkable and commits. The four existing directions become four callers.

Nothing changes on screen. This is the step that makes the next one free, and it removes three copies of a bug surface.

Add Y U B N for the diagonals, so the vi keys form the usual 3×3. With try_move in place each is two instructions and a call. Keep the arrow keys ($80-$83) mapped to the orthogonals, and consider the numpad digits as NetWhack uses them.

Four-way movement is the most noticeable difference between Rogueima and any other roguelike. This is an afternoon.

Walking was not the only thing that asked for a direction. open_door and do_talk each had their own copy of the key list, so after Step 2 you could walk diagonally but not open or talk diagonally — the same bug in two more places, which is exactly what Step 1 was meant to prevent.

The fix is the Step 1 move again, one level up. Four routines now do the work for all three prompts:

get_dir_key   ; read a key, fold it to upper case
decode_dir    ; AL -> CL = dx, DL = dy, ELM -> the name, carry = valid
dir_target    ; player + CL/DL -> X, Y, carry = on the map
print_dir     ; "  OPEN " + "NORTHEAST" + newline, preserving C and D

decode_dir is now the only place in the game that knows what a movement key is. Adding a fifth prompt that wants a direction — fire, throw, kick — costs two calls.

Two details worth keeping in mind:

• ELM and FLD are paired registers (EL:M, FL:D), so

FLD cannot hold a pointer while D holds a delta. print_dir

  takes its prefix in ''GLK'' and consumes it before any call.
* ''dir_target'' bounds-checks, which ''open_door'' and ''do_talk'' never
  did. Reading a glyph one step off the edge of the map used to read
  whatever followed the map data.

“ OPEN DOOR ” plus “NORTHEAST” is 21 characters and the message window is 19 wide, so the prefix lost the word the prompt above it already supplies.

Today the player moves and the world does not answer. Establish the order: the player acts, every monster acts, the clock advances. The T: counter in the status panel already exists — make a successful action advance it, and give move_mon its turn immediately after.

Everything from here assumes monsters get a turn when you take one.

move_mon was being called from inside draw_map, so monsters moved once per redraw, before the player's key had even been read. It is a call in the loop now, and the loop is the whole of the ordering:

main_loop:
    CALL @draw_map
    CALL @get_input         ; the player acts
    JNC @main_loop          ; ...or did not: redraw and ask again
    CALL @move_mon          ; now the world answers
    CALL @inc_game_time     ; and the clock moves
    JMP @main_loop

Every command routine answers the same question in the carry flag:

^ carry ^ meaning ^
| set   | the player spent a turn |
| clear | nothing happened |

get_input tail-jumps to those routines, so their carry is its carry and no dispatch code has to know which commands cost time. Walking into a wall, naming a direction with no door in it, and pressing an unknown key are all free — the world does not get to answer a non-move. M and G conjure things out of nothing, so they are free too; they are debug commands.

Giving monsters a real turn meant there had to be monsters, and there never had been:

• init_objects said “Write id = 0 for this record” but the

instruction was STB [ELM + I], and B was never zeroed. Every slot

  was born with a non-zero ID — that is, "in use" — so the ''SCANQUE'' in
  ''spawn_monster'' and ''create_gold'' never found a free one. **''M'' and
  ''G'' had been failing silently.** Whether this bit depended on what the
  title screen happened to leave in ''B''.
* ''MOD B, KL'' mixes a 16-bit destination with an 8-bit source. ''MOD''
  takes its width from the destination, so this read ''REGS[30]'' — past the
  end of the 16-bit register file — and ''B'' came back unreduced. Monsters
  and gold were being placed at coordinates like (56242, 15977), off the map
  and out of reach. Both spawners widen the dimensions into ''I'' and ''J''
  first now.
* ''move_mon'' still had a ''SED''/''CLD'' pair bracketing its commit —
  leftover CPU-trace instrumentation, harmless only for as long as no
  monster ever moved.

The assembler rejects mismatched widths for MOV but accepts them for arithmetic, and the CPU then indexes the register file with the raw encoding. MOD B, KL is not a typo the tools will catch. Worth a width check on the arithmetic path.

Numpad 5 and . both reach move_wait, which is now the one move that is nothing but time: it returns carry set without touching PX/PY, so the monsters get their turn and the clock advances. That makes it the way to watch monster behaviour without moving, which is what makes the next several steps testable.

map1_data is literal text — 40 lines of .bytes “####…”. That is fine for one static level and blocks everything else. Introduce a tile array with one byte of glyph and one byte of flags per cell, and a loader that expands the text into it when a level is entered.

Keep the text as the source format. It is readable, it diffs well, and hand-authored levels stay easy to write.

This is the pivotal step. Stairs, generated levels and line of sight all need per-tile storage, and doing any of them first means doing them twice.

Two bytes per square, row by row, at $030000 in bank 3 – 6,400 bytes for 80×40:

tile(x, y) = TILE_BASE + (y * width + x) * 2

SEEN and VISIBLE are defined now and set on every square, so the renderer behaves exactly as it did. Installing the machinery separately from switching it on is what keeps Step 10 small.

load_level expands the text into the structure on entry; tile_flags_for is the single place that decides what a glyph means, so the loader and put_glyph cannot disagree – which they would, the first time a door opened. is_walkable is a flag test now instead of a chain of glyph comparisons, and no longer walks the object list to get there.

The test for this step is that nothing changes on screen: the rendered display is byte-identical before and after, with the camera scrolled.

AND AL, @TF_WALKABLE is the first 8-bit immediate in the tree naming a label defined in a later file, and forward-reference patching got that wrong: it wrote the low byte, then wrote a second byte unconditionally, zeroing the next instruction's opcode. Here that opcode was a JZ, so is_walkable fell through its own branch and nothing on the map could be stepped on – from an image that assembled with no errors and no warnings.

Worth remembering as a shape: a program that assembles cleanly and behaves absurdly is worth a look at the emitted bytes, and then at the trace.

map1_id, map1_name, map1_up, map1_down and map1_dim already exist — the structure anticipates several levels and the stair coordinates are already declared. Generalise them into an array of level descriptors: id, name, dimensions, up and down stair positions, and a pointer to the tile data. One entry to begin with.

< and >. Entering a staircase switches the active level descriptor and places the player on the matching stair of the destination. The coordinates are already in the data.

The descriptor, which is the old map1_* fields plus the two pointers they were missing:

Every level is built at startup and keeps its own tile array, so levels persist – a door you opened is still open when you come back. There is nothing to gain by discarding one: a 26-level dungeon is under 170 KB.

enter_level mirrors the dimensions and tile pointer into level_dim and level_tiles, because tile_addr and draw_world read them per square and per cell.

Both commands check you are standing on the staircase, switch the descriptor, and put you on the matching stair of the destination – down arrives at the level's up stair, and the reverse. Both honour the turn contract: a flight of stairs is a turn, refusing to move is not.

place_stairs stamps < and > onto each level as it is built. Those coordinates had been in the data since the game was written and nothing had ever drawn them.

The table has two rows. Level 2 borrows level 1's text as a placeholder – Step 8 replaces that single pointer. Its tiles are already separate, which is what made the persistence testable: open a door on level 1, and the same square on level 2 is still shut.

Hand-authored, in the same text format. Proves the machinery of Steps 5-7 before any of it depends on a generator.

The machinery is already in place and exercised – what is left is content. One pointer in level_table row two changes from @map1_data to @map2_data.

BrynnWell, the well maze from NetWhack's src/netwhack/world/mapgen/BrynnWell.java – 20 x 30. Exactly one pointer in the table changed, which is what Steps 6 and 7 were for.

Glyph for glyph: NetWhack's . is our '' , ''# and + carry over, and its six secret doors (s) are ordinary doors here. There is no search command yet, so a secret door would be a wall you could never get through; they can go back to being secret once something can find them.

It is a 20 x 30 level, not a 20 x 30 maze padded out to match level 1. That needed two fixes in draw_world, which was the last place still assuming one map size:

• the camera clamp computed (map_width - view_width), which underflows

when the map is the narrower of the two. A map that fits has nowhere to

  scroll to, so the answer is zero.
* the render loop drew 58 x 23 squares unconditionally, so past the right
  edge of a narrow map it carried on into the start of the next row.
  Squares outside the map draw as nothing now.

Maps larger than the view always worked – that is the scrolling case. Everything else had carried per-level dimensions since Step 6. Level 1 is unaffected and provably so: its rendered screen is byte-identical before and after, walked to the same square with the same door open.

Verified by rebuilding the level out of its tile array and diffing against the Java source: all 30 rows match, with < and > stamped where the descriptor says.

Rooms and corridors, seeded from the RNG so a level is reproducible from its depth and seed. Appendix III of Writing Games in Assembly Language sketches this already, and NetWhack's DungeonMaker.java (633 lines) is the working reference.

With 16 MB there is no reason to discard a level once made: an 80×40 map is 3,200 bytes, so a 26-level dungeon fits inside a single bank. Levels can simply persist.

programs/rogueima/dungeon.sda. Fill the level with rock, mine one room in the middle, then repeatedly find a wall with exactly one floor square beside it and build on the far side, leaving a door in the wall you dug through.

That one-floor-neighbour rule is doing two jobs. It stops a level collapsing into a single cave, and it is also why every level comes out connected: each new piece is reachable through the door that made it. Connectivity is a property of the construction, not something checked afterwards.

Levels 3, 4 and 5 are generated, 78 x 22. LV_SRC of 0 in the level table means “there is no text to expand, build it”, and the generator writes LV_UP and LV_DOWN into the descriptor itself – a level that does not exist yet cannot say where its stairs are. Generated levels persist exactly like the hand-made ones.

addfeature in DungeonMaker.java reads:

switch (feature_type) {
    case 1:  success = makeshop(...); break;
    case 2:
    default: success = makeroom(...); break;
}

case 2: is an empty label falling straight into default:, so it builds a room like everything else. TileData.CORRIDOR exists and readmapline can produce one, but nothing ever generated one. The branch was never written rather than broken – which is why BDungeon levels are rooms hanging off rooms.

Writing it costs almost nothing, because a corridor is a room with one dimension collapsed to zero, and makeroom's geometry already handles that: building EAST with height 0 gives a.y = b.y = yloc, a single row. So rooms and corridors are one routine called with different sizes, and the feature roll now actually branches.

Dump the tile array and analyse it rather than looking at it. Level 3 came out 310 floor squares with all 310 reachable by flood fill; level 4, 388 of 388. Solid border, 18 and 20 doors, both staircases placed, and the two levels different from each other. Corridor squares – floor with exactly two opposite floor neighbours – numbered 70 on level 3.

Add the two flags to the tile structure from Step 5, and teach the renderer three states: visible (bright), seen but not visible (dim), unseen (blank). Then mark every tile seen and visible, so nothing changes on screen yet.

Installing the machinery separately from switching it on keeps the next step small and makes a regression obvious.

Each turn, clear visible, then walk a line from the player to every tile within a radius, stopping at anything opaque; mark what is reached visible and seen. NetWhack's Level.visline() and makevis() are the reference.

Integer Bresenham over tiles — not the PPU's line primitive, which draws pixels.

This is the step that changes how the game feels more than any other on this list. A lit corridor ahead and a remembered room behind is the difference between a map and a dungeon.

i to list, d to drop, and extend the existing ‚ pickup. Carried items are a queue, and the machine has INSQUE/REMQUE/SCANQUE for exactly this — obj.sda already uses them for objects lying in the world.

A shared header — kind, glyph, name pointer, weight — with a per-class payload after it. Weapons and armour first, because combat.sda already exists and will show the difference immediately.

w, W, T. Equipment slots feed the existing combat resolution: weapon damage, armour class.

Food, potions, scrolls, and a small effect dispatch table they trigger. NetWhack keeps 12 of each and an Effect class; a dozen effects is plenty to start.

A food clock, and e to eat. This is what turns wandering into a game: it is the reason to go down rather than explore forever.

HP returning slowly with time, resting to pass turns safely, and a proper death — tombstone, final score, and a return to the prompt rather than a hang.

Replace hardcoded monsters with data: glyph, name, hit points, damage, speed, depth range, behaviour flags. NetWhack's MobData has 60 entries; a dozen would already transform the game. Spawn by depth so descending means something.

NetWhack's PathMap.java is a Dijkstra map — flood the distance-to-player across walkable tiles, and every monster moves downhill. It replaces “step toward the player” with something that goes around corners, and it costs one pass per turn rather than one search per monster.

S to save and resume. The file services already exist behind INT $15. A high score table after that.

Steps 2, 7 and 11 — eight-way movement, stairs to a second level, and line of sight. That is the difference between a demo and a roguelike, and none of the three is large.