{"id":13337465,"url":"https://github.com/stefanbylund/zxnext_level9","last_synced_at":"2025-03-11T06:32:41.741Z","repository":{"id":230230682,"uuid":"472083862","full_name":"stefanbylund/zxnext_level9","owner":"stefanbylund","description":"Level 9 interpreter for Spectrum Next","archived":false,"fork":false,"pushed_at":"2024-06-07T11:00:44.000Z","size":15049,"stargazers_count":36,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-06-07T12:24:46.903Z","etag":null,"topics":["c","interpreter","sinclair","spectrum-next","text-adventure","zx-spectrum"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefanbylund.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-20T19:38:10.000Z","updated_at":"2024-06-07T12:24:49.734Z","dependencies_parsed_at":"2024-06-07T12:36:29.562Z","dependency_job_id":null,"html_url":"https://github.com/stefanbylund/zxnext_level9","commit_stats":null,"previous_names":["stefanbylund/zxnext_level9"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_level9","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_level9/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_level9/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_level9/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefanbylund","download_url":"https://codeload.github.com/stefanbylund/zxnext_level9/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213069685,"owners_count":15532834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","interpreter","sinclair","spectrum-next","text-adventure","zx-spectrum"],"created_at":"2024-07-29T19:14:22.699Z","updated_at":"2024-10-23T16:30:35.195Z","avatar_url":"https://github.com/stefanbylund.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Level 9 Interpreter\n\nThis is a port of the open source Level 9 interpreter *Level9* to ZX Spectrum\nNext. The original Level 9 interpreter was developed and used by the British\ncompany [Level 9 Computing](https://en.wikipedia.org/wiki/Level_9_Computing) to\ncreate text adventure games (interactive fiction) that would run on a variety of\n8/16/32-bit computers. Level 9 compiled their text adventure games to a custom\nbytecode language called A-code that was executed by an interpreter / virtual\nmachine called the A-machine. This was conceptually similar to Infocom's Z-code\nand Z-machine.\n\n*Level9* is a reverse-engineered Level 9 interpreter originally developed by\nGlen Summers in portable C code. David Kinder, Alan Staniforth, Simon Baldwin,\nDieter Baron and Andreas Scherrer have also contributed to the development of\nLevel9. The Level9 interpreter has been ported to many different systems. More\ninformation about Level9 and its source code is available on\n[GitHub](https://github.com/DavidKinder/Level9). In the following text, the\nterms *Level9* interpreter and Level 9 interpreter are used interchangeably.\n\nThe main challenge when porting the Level 9 interpreter to Spectrum Next is that\nit assumes a flat memory model where all memory is directly addressable and the\nloaded game story file is being kept in main memory. The Spectrum Next and its\nZ80 CPU is an 8-bit computer which can address only 64 KB of memory. Although\nthe Spectrum Next has 1 MB RAM where 768 KB is available to programs, this\nmemory has to be switched in to the 64 KB address space in 8 or 16 KB banks.\n\nThe design approach of the Spectrum Next port is to strip down the interpreter\nto fit in the 64 KB main memory and switch in the currently used part of the\ngame in the bottom 16 KB of the main memory. 12 KB is used for the text screen\n(using Timex hi-res mode), which leaves only 36 KB for the actual interpreter\n(including interrupt handling code and stack memory). See\n[memory_map.txt](memory_map.txt) for a detailed memory layout of the interpreter.\nFor comparison, the executable for the MS-DOS 16-bit version of the Level 9\ninterpreter is 87 KB.\n\nIn order to make the interpreter fit in this limited memory, certain parts of it\nhave been removed. For example, the following features have been removed:\nsupport for V1 games (see below), scanning of the game file for determining game\nversion (instead a gamedata.txt file is used for storing the game version),\nlisting of the game's dictionary and bypassing of the copy protection in V3/V4\ngames by trying every word in the game's dictionary.\n\nThe Level 9 interpreter runs Level 9 game story files. There are four main\nversions of the Level 9 game file format: V1 to V4. The Level 9 interpreter for\nSpectrum Next only supports V2/V3/V4 games in order to minimise the interpreter\nsize and since all V1 games were re-released as V2/V3 games anyway. This means\nthat all of Level 9's games in their later versions are supported by the Level 9\ninterpreter for Spectrum Next. When loaded by the interpreter for Spectrum Next,\nthe game story file is loaded into a contiguous set of 8 KB banks. When a\ncertain part of the game is referenced, e.g. an instruction in the code, that\nbank and the next bank are switched in to the bottom 16 KB of the main memory\nbefore being referenced.\n\nThere are two types of graphics used in the Level 9 games. The earlier games\nused line-drawn images that were memory-efficient and portable but very simple.\nThe later games used platform-specific bitmap images that were quite an\nimprovement. In order to reduce the interpreter size, the Level 9 interpreter\nfor Spectrum Next only supports loading and displaying of bitmap images in the\nSpectrum Next layer 2 320x256 NXI format. The NXI images are created with two\ncustom tools. The [convert_gfx](tools/convert_gfx) tool is used for converting\nthe line-drawn images in a Level 9 graphics file (picture.dat) to separate NXI\nimage files. The [convert_bitmap](tools/convert_bitmap) tool is used for\nconverting Commodore Amiga and Atari ST Level 9 bitmap image files to NXI image\nfiles.\n\nThe porting of the Level 9 interpreter to Spectrum Next is done using the\n[z88dk](https://github.com/z88dk/z88dk) C compiler. In addition to modifying the\ninterpreter source code to support bank switching, some C constructs have been\nchanged to generate better Z80 machine code. For example, unsigned integers and\nchars are used where possible, the z88dk fastcall calling convention is used\nwhere applicable, etc. More technical information about the port can be found in\nthe level9.c file.\n\n## User Interface\n\nThe screen of the Level 9 interpreter for Spectrum Next uses the Timex hi-res\nmode (or standard ULA mode) as background layer for displaying the text with a\nproportional font. The graphics is displayed using the layer 2 mode as the\nforeground layer and a clip window to limit its height. When there are too many\nlines of text to display on the screen at once, the message \"\u0026lt;MORE\u0026gt;\" will\nappear at the bottom left of the screen in the border area using two hardware\nsprites. The last entered line of input can be edited by pressing the EDIT key.\nThe graphics can be hardware scrolled up and down using the up and down arrow\nkeys to make more or less room for the text. If a PS/2 mouse is connected to the\nSpectrum Next, it can also be used to scroll the graphics up and down by dragging\nit with the mouse or using the mouse wheel.\n\nThe text colour can be changed by cycling downwards or upwards through a palette\nof 32 colours by pressing TRUE VIDEO and INV VIDEO, respectively. The default\ntext colour is light grey.\n\nThe table below shows the special keys used by the Level 9 interpreter for\nSpectrum Next:\n\n| Spectrum Key |   PS/2 Key    |                               Description                                |\n|--------------|---------------|--------------------------------------------------------------------------|\n| EDIT         | SHIFT + 1     | Edit last entered line of input.                                         |\n| UP           | SHIFT + 7     | Scroll graphics up.                                                      |\n| DOWN         | SHIFT + 6     | Scroll graphics down.                                                    |\n| TRUE VIDEO   | SHIFT + 3     | Change text colour by cycling downwards through a palette of 32 colours. |\n| INV VIDEO    | SHIFT + 4     | Change text colour by cycling upwards through a palette of 32 colours.   |\n| Mouse        | Mouse         | Scroll graphics up and down by dragging or by using the mouse wheel.     |\n\n## Games\n\nThe Level 9 Compilation is an unofficial compilation of all of Level 9's text\nadventure and multiple choice games for the Spectrum Next. Click on the link\nbelow to read more about it and download it.\n\n### [The Level 9 Compilation](compilation)\n\nThe Level 9 interpreter for Spectrum Next expects the Level 9 games to be\npackaged in the following way:\n\n```\n\u003cgame-directory\u003e/level9.nex\n\u003cgame-directory\u003e/gamedat*.dat\n\u003cgame-directory\u003e/gamedata.txt\n\u003cgame-directory\u003e/gfx/\u003cnumber\u003e.nxi\n\u003cgame-directory\u003e/gfx/prompt.spr\n\u003cgame-directory\u003e/gfx/mouse.spr\n```\n\nThe level9.nex executable file is the Level 9 interpreter itself. The\ngamedat*.dat game story file(s) is called gamedata.dat for single-part games and\ngamedat1.dat, gamedat2.dat etc for multi-part games. The game story files must\nnot have any superfluous file header. The gamedata.txt text file contains as its\nfirst character the digit 2, 3 or 4 representing the used game version V2, V3 or\nV4. The subdirectory gfx contains the location images in NXI format with the\nnaming convention \u0026lt;number\u0026gt;.nxi where \u0026lt;number\u0026gt; is the location image\nnumber used by the game. The file 0.nxi is the title image for V4 games. This\ndirectory also contains the sprites for the scroll prompt and mouse pointer.\nFor the multi-part multiple choice games, the location images are located in\nsubdirectories gfx/\u0026lt;game-part-number\u0026gt;/, one for each part of the game.\n\n## How to Build\n\nIf you want to build the Level 9 interpreter for Spectrum Next yourself, follow\nthe steps below:\n\n1. On Windows, you need [MinGW/MSYS](https://osdn.net/projects/mingw/),\n[Cygwin](https://www.cygwin.com/), [UnxUtils](https://sourceforge.net/projects/unxutils/)\nor similar for the basic Unix commands (GNU make, Bash, mkdir, rm, cp, cat and zip).\nMake sure the Unix commands are available in your PATH environment variable.\n\n2. Download and install [z88dk](https://github.com/z88dk/z88dk) v2.1 or later.\nAdd the environment variable ZCCCFG whose value should be \u0026lt;z88dk\u0026gt;/lib/config.\nAlso add \u0026lt;z88dk\u0026gt;/bin to your PATH environment variable.\n\n3. Download and install the latest version of the [CSpect](http://www.cspect.org/)\nor [ZEsarUX](https://github.com/chernandezba/zesarux) Spectrum Next emulator.\n\n4. Download the GitHub repository for the Level 9 interpreter for Spectrum Next\neither as an archive using the \"Code -\u003e Download ZIP\" button at the top of this\npage or with Git using the following command:\n\n```\n\u003e git clone https://github.com/stefanbylund/zxnext_level9.git\n```\n\n5. Go to the zxnext_level9 directory and enter the following command to do a\nclean build using the default configuration:\n\n```\n\u003e make clean all\n```\n\n6. Note: There are several configuration options when building and they are\nhandled by the configure.m4 file. Either edit the configure.m4 file or pass\nconfiguration options via make like this:\n\n```\n\u003e make clean all CONFIG=\"-DUSE_TIMEX_HIRES=1 -DUSE_GFX=1 -DUSE_MOUSE=1\" BUILD_OPT=true\n```\n\n7. Note: The z88dk SDCC compiler is very slow when using the highest level of\noptimisation. This can be controlled with BUILD_OPT=true or BUILD_OPT=false on\nthe make command-line. Setting BUILD_OPT=false or skipping it will give a much\nquicker build but without the highest optimisations.\n\n8. Note: Building with \"make debug\" instead of \"make all\" will create\nzxnext_level9/src/*.lis files containing the generated Z80 assembly interleaved\nwith the C source code. The generated file zxnext_level9/bin/level9.map contains\nall symbols and their addresses.\n\n9. Run the generated binary zxnext_level9/bin/level9.nex in the\n[CSpect](http://www.cspect.org/) or [ZEsarUX](https://github.com/chernandezba/zesarux)\nemulator. Use the particular game directory as the root directory in the emulator.\n\n## Source Code\n\nThis section briefly describes the main source files of the Level 9 interpreter\nfor Spectrum Next.\n\n* level9.c \u003cbr\u003e\nImplementation of the core part of the Level 9 interpreter. Theoretically, this\nfile is platform-independent and should not be modified when porting to a new\ntarget. However, the original implementation assumes a flat memory model and the\nloaded game story file being kept in its entirety in main memory. The Spectrum\nNext has only 64 KB addressable memory and a banked memory model. The\ninterpreter has been refactored to fit in the main memory and to load the game\nstory file into a contiguous set of memory banks that are mapped in as needed to\nthe bottom 16 KB of the 64 KB address space. Several changes have been done to\nimprove the performance for Spectrum Next.\n\n* main.c \u003cbr\u003e\nImplementation of the platform-dependent part of the Level 9 interpreter.\nHandles the user interface, terminal I/O, main loop, displaying of location\nimages, saving/loading of game state and playback of a script file.\n\n* interrupt.asm \u003cbr\u003e\nModule for setting up IM2 interrupt mode.\n\n* scroll_prompt.asm \u003cbr\u003e\nModule for showing/hiding the scroll prompt.\n\n* text_color.asm \u003cbr\u003e\nModule for changing the text colour by cycling through a palette of 32 colours.\n\n* layer2.c \u003cbr\u003e\nModule for loading, displaying and handling layer 2 320x256 images.\n\n* sprite.c \u003cbr\u003e\nModule for loading, displaying and handling hardware sprites. Used for\ndisplaying the scroll prompt and mouse pointer.\n\n* mouse.c \u003cbr\u003e\nIM2 ISR for Kempston mouse support. Updates the mouse pointer sprite and invokes\na supplied mouse listener.\n\n* image_scroll.asm \u003cbr\u003e\nModule for handling scrolling of the location image using the keyboard or mouse.\n\n* crt_driver_instantiation.asm.m4 \u003cbr\u003e\nCustom z88dk module for setting up the input and output terminals.\n\n* zx_01_input_kbd_inkey_custom.asm \u003cbr\u003e\nInput terminal driver subclass for handling special keys for location image\nscrolling, changing text colour, edit the last entry etc.\n\n* zx_01_output_fzx_custom.asm \u003cbr\u003e\nFZX output terminal driver subclass for standard ULA mode. Handles the scroll\nprompt and scroll limit computations.\n\n* tshr_01_output_fzx_custom.asm \u003cbr\u003e\nFZX output terminal driver subclass for Timex hi-res mode. Handles the scroll\nprompt and scroll limit computations.\n\n* in_key_translation_table.asm \u003cbr\u003e\nOverridden z88dk module for redefining the ASCII code for some special keys.\n\n* asm_in_mouse_kempston.asm \u003cbr\u003e\nOverridden z88dk Kempston mouse driver.\n\n* asm_in_mouse_kempston_wheel.asm \u003cbr\u003e\nOverridden z88dk Kempston mouse wheel driver.\n\n## Links\n\n* [Level 9 Interpreter](https://github.com/DavidKinder/Level9) \u003cbr\u003e\n  The source code of the open source Level 9 interpreter *Level9*, which the\n  Spectrum Next porting is based on.\n\n* [Level 9 Memorial](http://l9memorial.if-legends.org/html/home.html) \u003cbr\u003e\n  Information about Level 9 Computing and their games.\n\n## License\n\nThe *Level9* interpreter is licensed under the terms of the GNU General Public\nLicense version 2 and is copyright (C) 1996-2011 by Glen Summers and\ncontributors. Contributions from David Kinder, Alan Staniforth, Simon Baldwin,\nDieter Baron and Andreas Scherrer.\n\nThe *Level9* interface for ZX Spectrum Next is copyright (C) 2021 by Stefan\nBylund.\n\nThe QLStyle font is copyright (C) 2018 by Phoebus Dokos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanbylund%2Fzxnext_level9","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanbylund%2Fzxnext_level9","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanbylund%2Fzxnext_level9/lists"}