This is tutorial-like small project for ZX Next (TBBlue board) written in Z80N assembly (in sjasmplus syntax/dialect) by Peter Helcmanovsky (inspired by John McG.).
The final result looks like this (youtube video).
- how to kick off assembly-only project, producing NEX file
- how to set up Layer 2 and HW sprites
- how to write simple game-loop code handling controls
- partial how to set up your PC for development
- basic knowledge about Z80/Z80N instructions and assembly programming
- basic idea about ZX Next HW capabilities
The final result after all parts should be very simple game allowing the player to control main character and jump over snowballs, similar to the NextBASIC version done by John a while back.
The background image is in Layer2 256x192x8 mode, static image from BMP file, HW sprites are used for the player character and snowballs (graphics provided by John).
All the code and data required to build the final NEX file, with commits history to check the evolution of the project from beginning. Particular commits are marked with "Part_#number" tag, which is referenced from the tutorial text and you can download the sources and NEX file for each stage at releases.
The tutorial text is in the "wiki" part of this repository. It was written after the code was finished, to complement the source changes with ideas leading to those code changes and explaining some principles and design choices. Unfortunately, I was hoping for John to provide his own write up, giving the project extra insight of somebody new to asm game dev and reading code of someone else (me), but that didn't happen. If you feel confused by the tutorial even if you are supposedly target audience, please write down some notes what is unclear, and send me the feedback, I may add further FAQ or chapters, trying to explain such questions.
For the Next HW features description I use either wiki (particularly this page a lot), or the more compact form of technical info nextreg.txt (by core authors) and ports.txt (or extended/curated variants in Next system repo and ports).
Z80 instructions quick reference (Z80N variant), Z80N extended reference.
The code is written for sjasmplus assembler, which is command line tool. On the project page in "release" tab you can download windows executable for current latest release, if you are using different OS, the sjasmplus is cross-platform project written in C++14 with minimal dependencies, and should be easily buildable on any modern OS on any platform which: has GNU Make and has C++14 compiler (gcc/clang/...). If you have difficulties to built it on your platform, yet it fits the description, open the issue on github (I'm using linux, KDE neon distribution on x86_64 CPU). You can then use it as any other common compiler, for example by writing build rules in the Makefile or configuring build-task in your IDE/editor.
Sjasmplus online documentation is of course essential resource to fully understand the assembler directives, how they are used and their arguments, and what should be the result.
I'm personally using Kate text editor with the syntax-highlight rules from the sjasmplus project, and "Build plugin" set up to assemble asm file in editor (the build-rule I use mostly looks like "sjasmplus --fullpath --nologo --lst="%n.lst" --lstlab --msg=war "%n.asm"").
If you want to use VSC (VisualStudio Code/Codium), there are two alternatives for syntax-highlight and intelligent assistant: Z80 MacroAsm or Asm Code Lens, and then some more plugins: Z80 Assembly Meter, DeZog (VSC debug adapter), ...
Emulators: currently there are only two emulators with TBBlue-board emulation. #CSpect and ZEsarUX. Neither is perfect, but together and with all their modes they cover almost all possible Next-developer's needs (I have my own temporary fork of ZEsarUX with some extra modifications to make the TBBlue emulation closer to the 3.0+ cores of ZX Next). This tutorial project should work in any of the emulator both in "quick-boot" or "full-system-image" way of launch (and of course on the real board too).