Prologue

While answering questions about assembly programming at stackoverflow site, various forums and chats, I found out some recurring situations and themes.

If you want to program in assembly language for ZX Spectrum Next, you may have read the Z80 instruction set, or some online tutorial about how to display "Hello world" by calling rst $10, or maybe you downloaded last commit of this tutorial and opened the asm file in text editor, looking baffled at hundreds of lines of code, not sure where is the essence and what can be skipped and where to start. And maybe even after you have understood some short code provided by others, you tried to write your own, and suddenly not much of it works as expected or at all.

All of this is pretty normal when learning assembly programming (if it goes smoother than this, good for you, but you are probably not "normal" then ;) ).

There are no parts to skip, every letter in assembly code is of essence (except comments, those may be a bit more relaxed to interpret, or describe older version of code, at which point they may mislead you).

Also the assembly is not as guess-able programming language as "high level" programming languages, and you need to be very precise in assembly to achieve the expected results.

And there's certain amount of initial knowledge to gather before things will start to make some more sense, a bit like sound-speed barrier to overcome when you want to fly faster than Mach-one. But after breaking through this initial barrier, oh boy, you will fly, at least compared to BASIC or other interpreted languages. Will probably feel like supersonic speeds. :)

And even after decades of practice, you will be still checking that instruction reference guide to verify that dec h really doesn't modify carry flag, because if it does, your code logic is wrong.

But...

Contrary to how the paragraphs above may sound, the basics of assembly are actually super-simple. So simple that it takes even some time to realize how much simple it is, and then it takes even more time to realize how to achieve anything with such simple "calculator", which can only add or subtract very limited numbers in size, at limited speed, and has limited storage memory. It's not that difficult to learn all Z80 instructions, not that difficult to memorize memory layout of Next computer, or find the Next-register to modify, but to build more complex application from the simple instructions is the real challenge of assembly programming.

---

So how to?

Persist. Do a "rounds".

Take a look on the Z80 instruction table and read details of few instructions. Take a look at ZX Spectrum Next programming article about some sub-system, and read about NextRegisters or I/O ports driving the feature and possible values and configurations. Take a look on some working project source (pick smaller ones). Try to follow build instructions of the open source projects and see if you will succeed in building the binary. Try the binary in emulator, open the debugger, step over single instructions, one by one at time, watch how the values in registers are modified by each instruction, how memory is modified, and try to pair that with the theoretical description of the instruction. Read some book about programming in assembly. Do some math on paper to verify you understand how computers encode everything in zeroes and ones. Write a small bit of your own code and debug it.

And make "rounds" through all of this, don't stay stuck on single detail you can not yet understand or grasp, eventually it will all come together and things will start slowly make sense. It will become easier to recognize where your assumption went wrong, and why that description said something different than you initially thought, after re-reading it like fifth time in a month.

Also expect the assembly programming to be very machine-like. A very simple machine. The CPU of ZX Spectrum Next can add and subtract two values, shift bits left or right and read and write to memory or I/O port. Based on the content of particular register or "flag" it can also conditionally control the execution flow of the code. And that's roughly all it can do!

Whatever higher-level concept like image, sound, keyboard or score is on your mind, you have to break it down multiple times, encode it as byte values and use the chain of basic arithmetic operations to achieve complex results. The Next comes also with powerful HW features which are breeze to control even for very fresh assembly programmer, making certain tasks like "making sprite visible" a question of setting only three values in the system, but even on Next the majority of tasks will boil down to somewhat mundane long chains of trivial arithmetic operations or moving values from one part of memory to other and then "suddenly" the mess of the few byte values becomes a sound or animation of object or new file on the disk, if you did architect those small simple steps to achieve such goal.

In this regard the assembly is very simple programming language. There are only few instructions and only few and very limited things you can do in single cycle of CPU. Connecting these simple actions into larger whole is the challenging part, after you get through the initial barrier of understanding the instructions.

And while programming in assembly, you have to learn to zoom in and out in your mind, from the high level abstraction what you want to achieve on the screen down to the low machine level where making sprite visible means setting bit 7 of sprite attribute to value one, zooming quickly through multiple layers of abstraction.

---

Now this tutorial-like project is not full book about programming in assembly. I expect you to learn basics of Z80 instructions elsewhere, also don't underestimate the understanding of how numbers in computer are encoded, how to convert from binary to decimal or hexadecimal formatting of the same numeric value, why single byte can have only values from 0 to 255, and you should often cross-check the particular use of HW feature against the Next manual or wiki to understand all the details down to last bit. This all is out of focus in this project.

This project will provide you with working assembly source, written in relatively simple way, so you can assembly it yourself into the NEX file, launch it in emulator, and toy with it in the debugger until everything fits together and makes sense (while cross-checking your assumptions with various other references and books).

Go to releases Part 1, download the source (or clone the whole repository if you are familiar with git, and checkout the Part_1 tag), and use the README file and your own preference to collect the tools, assembler, emulators and start with your development environment configuration. Open the source file in your favourite programming editor, check if it can do Z80 asm syntax highlight, try to build source from command line by calling sjasmplus assembler, try to configure your editor to do this for you in some simple way, try to launch it in emulator (probably building some bat/script/alias with all the required options to make it work) and try to enter the debugger in emulator, and learn to control it.

Once you have this basic setup done, dive into the source itself, read the comments, experiment with debugger to see if every instruction does what you did expect and you may try to modify some of them to see if you can achieve some planned change on screen, or even unplanned.

If you get stuck on something, maybe try for a while something else, doing the "rounds" and come back later. If you are still stuck on the same thing, don't hesitate to ask, for example in discord server for Next, somebody will hopefully get you unstuck and on the right path.

by Peter Helcmanovsky, aka "Ped" from 7 Gods demo group (being active on ZX Spectrum demo-scene back in 1993-1997).