20240104
The disassembly is now built with SkoolKit 9.0.
20210529
This update focuses on improving the summaries at the start of every routine or piece of data that the disassembly describes.
- Improvements to main disassembly commentary
- The descriptions at the start of every section have been improved.
- The routine titles (those used on the main memory map) have been made more concise and now match the routine label.
- Many cross references have been added.
20210328
This is a small fix update.
- Changes
- Reinstated the animations on the Characters page and added descriptions, including a corrected version of the guard facing forward.
20210319
The disassembly is now built with SkoolKit 8.4.
- Changes
- Removed animations from Characters page due to them breaking SkoolKit.
- Improvements to main disassembly commentary
- Prologue: Was synced with the C port changes.
- Improvements to disassembly symbols only
- masked_sprite_plotter_16/24_enables -> plot_masked_sprite_16/24px_enables
20200812
The disassembly is now built with SkoolKit 8.2.
- Major changes
- SkoolKit has deprecated Skool file templates, so the disassembly was turned back into a control file. This required some changes to rfix and co. to allow the conversion.
- Improvements to main disassembly commentary
- $AFDF/collision: Was improved and synced with the C port changes.
- $BB98/restore_tiles: Was synced with C port changes.
- $C6A0/move_a_character: Had an incorrect comment fixed and a comment updated.
- Improvements to disassembly symbols only
- room_*_BREAKFAST -> room_*_MESS_HALL
- vischar_TOUCH_ENTERED -> vischar_DRAWABLE
- $B89C/locate_vischar_or_itemstruct -> get_next_drawable
- $C6A0/move_characters -> move_a_character
- $DBEB/get_greatest_itemstruct -> get_next_drawable_itemstruct
- Other changes
- Some grammar issues, broken paragraphs and links were fixed.
- Removed "nearly" from "nearly complete" on the diassembly front page.
20190629
The disassembly is now built with SkoolKit 7.2.
- Major changes
- 100% of the disassembly has now been rewritten in plain English.
- Improvements to main disassembly commentary
- $81DA/interior_mask_data gains a structure description for mask_t.
- The last of the 0x syntax has been replaced with $.
- Improvements to disassembly symbols only
- Renamed vischar_FLAGS_* constants for pursuit to vischar_PURSUIT_*.
- Some old location constants were removed.
- The stylesheet now draws a thin border under each contiguous comment.
20190313
The rewrite of the disassembly commentary continues. About 90% of the disassembly has now been rewritten in plain English.
- The disassembly is now built with SkoolKit 7.1.
- The 'make install' step is no longer required.
- The .skool file must sit alongside its .ref file now, so no longer gets put in the 'build' dir.
- @assemble directive values were renumbered.
- Improvements to main disassembly commentary
- The file prologue now has a "common types" section for types used across the file. The policy otherwise is to define a table next to where the structures are first used.
- Music related changes
- Renamings
- $F52C/get_tuning -> frequency_for_semitone
- $FA48/music_tuning_table -> semitone_to_frequency
- Where the individual tunes start are identified, as are their names.
- All of the notes in semitone_to_frequency are now documented.
- The spare space at the end of semitone_to_frequency is noted (it's only spare when the menu screen is running).
- Renamings
- vischar_BYTE7_LOCATABLE -> vischar_TOUCH_ENTERED
- vischar_BYTE7_MASK_HI -> vischar_BYTE7_COUNTER_MASK
- $6BAD/rooms_and_tunnels: Added a table describing the room definition format.
20180825
Small tweaks to the HTML output only.
- Improved colour contrast in the CSS stylesheet.
- The page footers now advertise the disassembly as "nearly complete" rather than "incomplete".
20180822
Huge rewrite of the disassembly commentary. The first 50% of the disassembly has now been rewritten in (hopefully!) plain English prose.
20180419
The disassembly is now built with SkoolKit 6.4.
- Major changes
- Updated for SkoolKit 6.4 and Python 3.
- Changes contributed by Richard Dymond.
- Added a game section:
- The instructions from the original cassette inlay are now included as the first section of the disassembly. The text was imported from WoS and the original diagrams were redrawn. I've even identified exactly the right font that the original manual used and used that.
- A page about how to complete the game has been added. Presently this includes the 1994 Vaxalon solution and a list of escape conditions that I've added: it lists the valid items which you need to successfully escape the camp.
- Enabled assembly labels in the disassembly (I should have done this from the start).
- Additions to peripheral disassembly
- Improvements to peripheral disassembly
- The items now all have descriptions (todo: needs more links).
- The masks page is now divided into two parts for exterior and interior.
- The logo now has alt text set.
- The copyright statement used at the footer of every disassembly page has been expanded.
- The barbed wire from the game is now drawn across the top of the page footer.
- We no longer specify the base font size to let the user's preference take precedence.
- We now use ITC Berkeley Oldstyle Std for the disassembly if browser has it. This is the font used for the original game's casettte inlay body text. Cambria is used as a fallback as before.
- Corrections to peripheral disassembly
- The map description has been corrected now that I understand that there's a single exterior tile set which uses a sliding window rather than three separate tile sets.
- The facts page has had various edits.
- Additions to main disassembly commentary
- locations: Added @keeps.
- plot_single_glyph: Added label for plot_single_glyph.
- wave_morale_flag_3: Added note about bitmap_flag_up/down overlapping.
- define_key_prompts: Added label for define_key_prompts
- ~$F0F8: Added memory map for $F0F8 onwards.
- Improvements to main disassembly commentary
- The pursuit modes: vischar_FLAGS_BRIBE_PENDING, vischar_FLAGS_BIT1 and vischar_FLAGS_SAW_BRIBE weren't individual flags but instead an enumeration. They are now vischar_FLAGS_PURSUE, vischar_FLAGS_HASSLE, vischar_FLAGS_DOG_FOOD and vischar_FLAGS_SAW_BRIBE.
- Numerous renamings:
- queue_message: queue_message_for_display -> queue_message
- iso_pos_x: screenpos_x -> iso_pos_x
- iso_pos_y: screenpos_y -> iso_pos_y
- route_to_permitted: byte_to_pointer -> route_to_permitted
- end_of_breakfast: breakfast_time -> end_of_breakfast
- set_hero_route: set_hero_target_location -> set_hero_route
- set_prisoners_and_guards_route: set_prisoners_and_guards_location -> set_prisoners_and_guards_route
- set_prisoners_and_guards_route_B: set_prisoners_and_guards_location_B -> set_prisoners_and_guards_route_B
- set_route: set_target -> set_route
- store_route: store_location -> store_route
- character_bed_state: byte_A13E_is_nonzero -> character_bed_state
- character_bed_vischar: byte_A13E_is_zero -> character_bed_vischar
- character_bed_common: byte_A13E_common -> character_bed_common
- set_route_go_to_yard: set_location_0x000E -> set_route_go_to_yard
- set_route_go_to_yard_reversed: set_location_0x048E -> set_route_go_to_yard_reversed
- set_route_go_to_breakfast: set_location_0x0010 -> set_route_go_to_breakfast
- charevnt_breakfast_state: byte_A13E_is_nonzero_anotherone -> charevnt_breakfast_state
- charevnt_breakfast_vischar: byte_A13E_is_zero_anotherone -> charevnt_breakfast_vischar
- charevnt_breakfast_common: byte_A13E_anotherone_common -> charevnt_breakfast_common
- searchlight_clip_left: searchlight_related -> searchlight_clip_left
- get_target: get_next_target -> get_target
- C7D4 (character_event): Added a note about the sixth prisoner bug.
- charevnt_solitary_ends: charevnt_handler_4_solitary_ends -> charevnt_solitary_ends
- charevnt_commandant_to_yard: charevnt_handler_6 -> charevnt_commandant_to_yard
- charevnt_hero_release: charevnt_handler_10_hero_released_from_solitary -> charevnt_hero_release
- charevnt_wander_left: charevnt_handler_1 -> charevnt_wander_left
- charevnt_wander_yard: charevnt_handler_2 -> charevnt_wander_yard
- charevnt_wander_top: charevnt_handler_0 -> charevnt_wander_top
- charevnt_bed: charevnt_handler_3_check_var_A13E -> charevnt_bed
- charevnt_breakfast: charevnt_handler_5_check_var_A13E_anotherone -> charevnt_breakfast
- charevnt_exit_hut2: charevnt_handler_7 -> charevnt_exit_hut2
- charevnt_hero_sits: charevnt_handler_9_hero_sits -> charevnt_hero_sits
- charevnt_hero_sleeps: charevnt_handler_8_hero_sleeps -> charevnt_hero_sleeps
- automatics: follow_suspicious_character -> automatics
- vischar_move_x: vischar_at_pos_x -> vischar_move_x
- vischar_move_y: vischar_at_pos_y -> vischar_move_y
- target_reached: bribes_solitary_food -> target_reached
- get_target_assign_pos: get_next_target_and_handle_it -> get_target_assign_pos
- route_ended: ran_out_of_list -> route_ended
- get_route: element_A_of_table_7738 -> get_route
- CHECK:
- set_character_route: set_character_location -> set_character_route ** CAN'T BE BOTH
- set_character_target -> set_character_route ** CAN'T BE BOTH
- "Further notes" were reduced.
- locations (locations): Improved description.
- item_actions_jump_table: Commented return ops.
- charevnt_breakfast_vischar: Removed hacking note now I've confirmed it's a test for the commandant.
- zoombox_tiles: Added UDGs for barbed wire zoombox tiles.
- C896: Uses bell_RING_PERPETUAL.
- All remaining single dash comments were removed.
- Corrections to main disassembly commentary
- Fixed spelling of "pursue" everywhere.
- route_7833: Fixed name: route_7738 -> route_7833.
- red_cross_parcel_reset_data: Should have been room_20_REDCROSS, not an item.
- AA0C: Fixed various calculations in the shunt_map routines' commentary.
- spawn_characters: HL is being read as part of screen x calc, not written through.
- C41F (spawn_characters): A 'SUB' was missed resulting in an incorrect comment.
- C9AA (character_behaviour): Fixed comments which transposed indoors and outdoors.
- Improvements to disassembly symbols only
- characterstruct_BYTE0_MASK -> characterstruct_CHARACTER_MASK
- doorpos_FLAGS_MASK_DIRECTION -> door_FLAGS_MASK_DIRECTION
- vischar_BYTE2_BIT7 -> route_REVERSED
- vischar_FLAGS_DOOR_THING -> vischar_FLAGS_TARGET_IS_DOOR
- Corrections to disassembly symbols only
- ~$CD6A: ITEM_ROOM macro takes a room_no, not an item_no.
20170325
The disassembly is now built with SkoolKit 5.4.
- Added:
- Defined door_NONE ($FF) and used it.
- Split door_LOCKED into door_LOCKED and door_REVERSE. door_REVERSE is the flag passed around when a door is to be entered from the opposite side.
- Fixed:
- Merged the exterior tilesets together. It turns out that supertiles can contain tiles with indices which go beyond their respective tile set and into the next. The exterior tilesets therefore ought to be a single tileset.
- 68F2 Fixed some FALL THROUGHs. These had migrated down to the end of the routine to the point where they were wrong. The original intent was to re-express the disassembly as an if-else, but that means that the commentary shows an inverted sense of of the assembly. Rewrote the commentary to follow the code.
- action_key_0 open_door should not have fallthrough at end.
- AB07 move_map had an inverted test.
- B31C reset_outdoors had an incorrect room_index.
- A81D plot_topmost_tiles had an incorrect map_buf offset.
- B096 incorrect test fixed.
- restore_tiles restore_tiles: Replaced blank lines with semis to avoid broken build.
- TheGreatEscapeGraphics.ref: Fiddle address ranges to avoid glitchy tileset images.
- searchlight_movements searchlight_movements: Fixed misnumbered address lines. (Showed up as a dodgy game image).
- The ran_out_of_list "arrive here" comments were incomplete.
- mask_against_tile mask_against_tile: Increment is not a supertile stride, but the mask buffer stride.
- Fixed various incorrect comments claiming that hero_map_position_x is hero_map_position.y.
- Fixed some incorrect sprite references.
- select_tile_set: Fixed register usage for select_tile_set.
- BB9F was checking for vischar_FLAGS_EMPTY_SLOT, not room_NONE.
- $7CFE is message_queue + 2.
- snipping_wire_new_inputs and collision_new_inputs values are summed not ORed.
- route_ended_0 JR C means less than, not equality.
- get_target_1 isn't a call to transition() it's a call to get_door_position().
- Removed:
- vischar_BYTE2_MASK
- gates_and_doors_MASK
- characterstruct_BYTE6_MASK_HI. Replaced with ~characterstruct_BYTE6_MASK_LO.
- doorpos_FLAGS_MASK_ROOM. Replaced with ~doorpos_FLAGS_MASK_DIRECTION.
- Named / renamed:
- locked_doors gates_and_doors -> locked_doors
- vischar_BYTE14_CRAWL -> vischar_DIRECTION_CRAWL
- Added vischar_DIRECTION_MASK to replace literal value 3 masks.
- vischar.b0C -> animindex
- plot_masked_sprite_16px_x_is_zero masked_sprite_plotter_16_wide_searchlight -> masked_sprite_plotter_16_wide_item - It's used for items only and is nothing to do with the searchlight. No idea why I thought it was.
- plot_masked_sprite_16px masked_sprite_plotter_16_wide -> masked_sprite_plotter_16_wide_vischar
- plot_masked_sprite_24px masked_sprite_plotter_24_wide -> masked_sprite_plotter_24_wide_vischar
- doors door_positions -> doors
- get_door get_door_position -> get_door
- animations: anim_A -> anim_walk_tl etc.
- purge_invisible_characters purge_visible_characters -> purge_invisible_characters
- plot_sprites locate_vischar_or_itemstruct_then_plot -> plot_sprites
- picking_lock picking_a_lock -> picking_lock
- action_lockpick open_door -> get_nearest_door
- Renamed all the bitmaps and masks so they're in sequence from the perspective of the sprites[] table.
- animations character_related_pointers -> animations
- cutting_wire snipping_wire -> cutting_wire
- in_solitary morale_1/2 -> in_solitary, morale_exhausted
- vischar_move_x move_character_x/y -> vischar_at_pos_x/y
- vischar.p04 -> pos
- handle_target sub_CB61 -> handle_target
- route_ended sub_CB2D -> ran_out_of_list
- get_target_assign_pos sub_CB23 -> get_next_target_and_handle_it
- iso_pos_x map_position_related_x/y -> screenpos_x/y
- interior_doors door_related -> doors -> interior_doors
- calc_vischar_iso_pos_from_vischar reset_position -> calc_vischar_from_mi_pos
- vischar_BYTE7_BIT6 -> vischar_BYTE7_TOUCHING
- vischar_FLAGS_BIT6 -> vischar_FLAGS_DOOR_THING
- mask_pointers exterior_mask_data_pointers -> mask_pointers
- mask_tiles exterior_tiles_0 -> mask_tiles
- render_mask_buffer mask_stuff -> render_mask_buffer
- get_target sub_C651 -> get_next_target
- restore_tiles called_from_main_loop_3 -> restore_tiles
- Commentary:
- rvc_copy_mi in reset_visible_character: Comment on how the DOS version resets stoves and crates when re-entering a room.
- Experiment rewriting animate called_from_main_loop_9 commentary in the usual assembly one-comment-per-line style.
- Note that multiply multiply sets D to zero.
- reset_game reset_game: 'Reset score' part starting at B772 resets a number of other vars too.
- Tighten up the 'other things' list near the start of the .skool file now that we know how the mask buffer is laid out.
- Refer to variables in commentary using structure member names.
- BC31 is multiplying C by 192.
- zoombox_fill is computing zoombox_y * 192.
- Add a note about topmost bits being discarded by ADD A,A.
- Clarified: CB41 forces the subsequent jump.
- Numerous other comment tweaks.
- Improved:
- restore_tiles restore_tiles reworking.
- render_mask_buffer render_mask_buffer reworking:
- mask_left_skip byte_B837 & co. are now clip_{x0,y0,width,height}.
- Fixed B9AF comparison.
- multiply() returns HL. Zeros D as a side effect.
- character_meta_data_commandant character_meta_data is now defined as words, not bytes.
- The coloured map now uses a checkerboard pattern to show position of the supertiles. The separately listed supertiles also use a checkerboard to show the position of the UDGs.
- Bugs:
- B500 get_nearest_door doing 8 iterations instead of 7.
- AA1D shunt_map_right buffer length is a byte too long.
- SkoolKit:
- TheGreatEscape.py
- Split out map and mask extraction methods.
- Defined all (useful) attributes.
- Improved documentation comments.
- Marked methods as API (used from .skool) or Internal (used from .py only).
- Fixed some, but not all, flake8 warnings.
- room_object_info: Removed duplication in printing code.
- Suppressed warnings from skool2asm.
- Added a "z80" Makefile rule to exercise SkoolKit 5.2's skool2bin | bin2sna pipeline.
- Other:
20160326
The disassembly is now built with SkoolKit 5.1.
- Added a couple of short facts to Trivia about unused room indices and unused interior object indices.
- Re-enabled the input and output register headings in the stylesheet.
- Did a big reformat pass to unwrap lines.
- Stripped trailing whitespace too.
- Tidied up all the 'sampled' lines where I've recorded addresses in use.
- Removed:
- All comments which duplicated the adjacent instruction.
- These were useful in the control file which didn't list an instruction but not in the skool file which does.
- All single dash comments.
- These were only used in the control file to stop regions coalescing.
- Unused statictile defs.
- Named / renamed:
- map_buf is map_buf - added a label.
- Fix: 6CF8 roomdef_6_corridor -> roomdef_8_corridor.
- Fix: roomdef_5_hut2_right_bed_D roomdef_3 beds -> roomdef_5 beds.
- Fix: character_16_GUARD_DOG_2 -> character_17_...
- searchlight_states -> searchlight_movements.
- Fix: References in comments to plot_masked_sprite_16px missed when it was renamed masked_sprite_plotter_16_wide.
- Fix: Some old names had crept in.
- Typo: action_shove -> action_shovel.
- stashed_A -> touch_stashed_A.
- Patches:
- Added @bfix for A2C6 incorrect iteration count resulting in a ROM write to $1A42.
- Added @rfix for range redundant self-modifying code.
- Added @rfix fixes for redundant jumps, missing RET, bug fix for item_is_discoverable.
- But note that currently enabling these fixes will create a broken TAP file.
- Commentary:
- expand_object_3 is *not* a needless reload (but it is in the C conversion).
- Added comments to the bitmap_font at bitmap_font.
- Added overall notes to the disassembly.
- Updated style notes.
- Game notes whipped into nicer state.
- Item bitmap descriptions now show the dimensions.
- Commented the zoombox_tile definitions.
- Annotated the wall defs.
- Stopped having fences as a separate array.
- Fix: Comment on exterior_tiles_3 had wrong number of tiles.
- Fix: Old names for the collapsed tunnel object were kicking around.
- Fix: The C896 bell ringing test was inverted.
- Synced doorpos_FLAGS with C version.
- + Various fixes.
20151102
Changelog begun and populated retrospectively.
20151028
28th October 2015 update.
- The disassembly was migrated from a control file to a skool file.
- The disassembly is now built with SkoolKit 5.
- The searchlight movement block at searchlight_movements was decoded and renamed to searchlight_states.
- Documented the mystery data block at FEF4 as much as possible.
- Modified from a contribution from Richard Dymond.
- Added a tap2sna script.
- Contributed by Richard Dymond.
- On the objects page unused objects are now ignored rather than producing duplicated images.
- Rooms are now decoded to a Rooms page.
- Statistics are given for each room including object counts and highlighting when an object's use is unique to that room.
- Sprite definitions were renamed to match the C version:
- 'away' or 'towards' rather than 'top left' or 'bottom right'.
- Room and interior object naming was rationalised for the benefit of room decoding.
- We now suffix compass directions to indicate where an interior object faces (NW, NE, SE, SW).
20150123
23rd January 2015 update.
- The super tiles are now coloured by their group. The exterior map is now additionally presented with the supertile groups coloured.
- Fixed: An earlier change to set_game_window_attributes/set_game_window_attributes to replace the routine with memset() was incorrect.
- Moved all game state variables to game status buffer directives.
- CSS: Fixed various mis-coloured elements, changed to Cambria for the main font.
- Assembly improvements:
- Added isubs.
- Suppressed any and all .ctl warnings with @nowarn or @keep.
- Wrapped CALL directives in HTML[].
- Added labels for directly-referenced objects, like bed objects.
- Set line width and warning directives.
- Changed "TBD" bytes to mask bytes.
- Fixed incorrect makefile dependency.
20141125
15th November 2014 update.
- Documented the map tiling / tokenisation / compression technique on the map page.
- Separated the concepts of player and hero. The player is the player and the hero is the guy on the screen. Formerly everything was described in terms of player.
- I was using 'vertical offset' or 'vo' in places when this can be more simply be called 'height'.
- Changes were made to get assembly output working:
- Many labels were added for the benefit of the generated assembly listing.
- Wrapped HTML-only elements in HTML or UDGTABLE.
- Makefile:
- Added an 'all' rule which builds everything
- Made rules more generic
- Added bin and tap rules.
- Made project name a variable in the Makefile.
- Renamed rules (make tge -> make disasm).
- New functions:
- within_camp_bounds becomes its own function, within_camp_bounds.
- plot_ringer is promoted to its own function.
- set_morale_from_A is promoted to its own function.
- Split main_loop out of main_loop_setup.
- Renamed:
- solitary_transition_thing becomes solitary_pos.
- byte_9F15 becomes permitted_bounds.
- indoors_delay_loop becomes interior_delay_loop.
- sub_DD02 becomes item_visible.
- setup_sprite_plotting becomes setup_vischar_plotting.
- outdoors_mask_data becomes exterior_mask_data.
- Broke the following structures down so that each field is listed:
- Turned inline C++-style comments into 'D' lines in various places including:
- Fixes:
- DC98 in setup_item_plotting is an exclusive-or, not an or.
- expand_object: An essential width counter assignment line went walkabout.
- Self-modified addresses are expressed as ' + 1' in supertile_plot_vertical_common and expand_object.
- Split the three entries in permitted_bounds up.
- Added lists of readers and writers to important variables.
- Split messages_table and the adjacent game messages apart.
- roomdef_bounds: These are room bounds; this was previously just a suspicion.
- Split roomdef_object_bounds into roomdef_object_bounds_count and roomdef_object_bounds.
- Note that $81D0 onwards is unreferenced bytes.
- item_bitmaps_and_masks: Provided dimensions for bitmap and mask blocks.
- Added note about check_menu_keys exiting by using POP BC to remove the outer calling function's return address off the stack.
- Also noted that choose_keys relies on A' being zero which happens only because the keyboard routine is at $FE00.
20141019
19th October 2014 update.
