SpecNext Wiki - User contributions [en-gb]

NextBuildStudio:Main Page

2026-02-24T17:04:30Z

Em00k:

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect] which can be downloaded from Mike's itch on install.

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://zxnext.uk/nextbuildstudio NextBuild Studio Download] (includes everything : Boriel ZX Basic, ability to download CSpect emulator, ZX Next OS image and NextBuild scripts)

* For Linux machines, you will need '''mono-complete''' installed to run CSpect.

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(n*frames)
WaitRaster(raster_line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2026-02-24T17:04:02Z

Em00k:

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect] which can be downloaded from Mike's itch on install.

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://zxnext.uk/NextBuildStudio NextBuild Studio Download] (includes everything : Boriel ZX Basic, ability to download CSpect emulator, ZX Next OS image and NextBuild scripts)

* For Linux machines, you will need '''mono-complete''' installed to run CSpect.

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(n*frames)
WaitRaster(raster_line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-09-15T01:16:41Z

Em00k: /* Timing and Synchronization */

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://zxnext.uk/NextBuildStudio NextBuild Studio Download] (includes everything : Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

* For Linux machines, you will need '''mono-complete''' installed to run CSpect.

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(n*frames)
WaitRaster(raster_line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuild:Main Page

2025-09-15T01:15:32Z

Em00k: Em00k moved page NextBuild:Main Page to NextBuildStudio:Main Page: NextBuild is now NextBuildStudio

#REDIRECT [[NextBuildStudio:Main Page]]

NextBuildStudio:Main Page

2025-09-15T01:15:31Z

Em00k: Em00k moved page NextBuild:Main Page to NextBuildStudio:Main Page: NextBuild is now NextBuildStudio

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://zxnext.uk/NextBuildStudio NextBuild Studio Download] (includes everything : Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

* For Linux machines, you will need '''mono-complete''' installed to run CSpect.

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-09-15T01:14:06Z

Em00k: /* Requirements */

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://zxnext.uk/NextBuildStudio NextBuild Studio Download] (includes everything : Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

* For Linux machines, you will need '''mono-complete''' installed to run CSpect.

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-09-15T01:12:11Z

Em00k: /* NextBuild v8 */

= NextBuildStudio =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuildStudio is IDE featuring tools libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] to create software for the ZX Spectrum Next. Version 9 introduces significant changes, including NEX file generation that contains all your assets in a single file, full sprite, palette and tile editing. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

NextBuildStudio is a fork of [https://code.visualstudio.com/ Visual Studio Code], with simple installation for both Windows and Linux operating systems. NextBuildStudio is fully integrated tightly with VSCode.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

Kempston Joystick

2025-09-10T09:35:04Z

Em00k:

{{Port
|Number=$xx1F
|NumberDec=31
|PortMask=%---- ---- 0001 1111
|ShortDesc=Reads movement of joysticks using Kempston (Joystick/Gamepad) interface.
|Readable=Yes
|Writable=No
|Subsystem=Input
}}
{| class="wikitable"
!rowspan="2"| Bit !!colspan="2"| Function
|-
! Kempston joystick !! MD controller
|-
| 7 || 0 || start button
|-
| 6 || 0 || A button
|-
| 5 || Fire 2 || C button
|-
| 4 || Fire 1 || B button
|-
| 3 ||colspan="2"| up
|-
| 2 ||colspan="2"| down
|-
| 1 ||colspan="2"| left
|-
| 0 ||colspan="2"| right
|}
For all bits 0 = not pressed / 1 = pressed

since core3.1.4 the X/Y/Z/mode buttons of 6-button controllers are not read by the FPGA (and Fire 1 is "B" button, this page and some other documentation was mentioning button "C", but seems like it was "B" all the time, or got remapped in core3.1.4).

Note for non-programmers: the Next board does read fire1(B)/fire2(C)/A/start buttons of controller and provide the state for SW through this port, but that does not imply the SW will react to the extra buttons. Actually majority of legacy SW was not aware of existence of joysticks with more than one fire button, the "fire2" input in Kempston interface did appear very late in the life cycle of ZX when game producers already moved onto more modern platforms. So support for second fire button or full four button of MD pads needs to be present also in the code of the particular game, either patched version of legacy game, or new production designed for ZX Next.

Extended MD Pad Buttons Register

2025-09-10T09:33:27Z

Em00k:

{{NextRegister
|Number=$B2
|Readable=Yes
|Writable=No
|ShortDesc=Reading additional buttons on MD pads (Joystick/Gamepad)
}}
bit 7 = 1 if Right Pad X pressed
bit 6 = 1 if Right Pad Z pressed
bit 5 = 1 if Right Pad Y pressed
bit 4 = 1 if Right Pad MODE pressed
bit 3 = 1 if Left Pad X pressed
bit 2 = 1 if Left Pad Z pressed
bit 1 = 1 if Left Pad Y pressed
bit 0 = 1 if Left Pad MODE pressed

Turbo Sound Next

2025-05-25T12:01:42Z

Em00k: /* AY-3-8912 layout */

Turbo Sound Next is the audio system integrated on the Spectrum Next. It features 3 AY-3-8912 sound chips as used in the Spectrum.

A MOS 6581 (SID), as used on the Commodore 64, was experimentally added to the FPGA during development but it was later removed due to the large amount of space it takes up (it is 4 times as big as an AY).

For information on playing back PT3 files, have a look here : [[https://wiki.specnext.dev/Code:PT3 Various PT3 replay methods]]

= Chip Selection =
{{PortNo|$FFFD}} controls the selected chip and enables and disables stereo channels per chip. {{NextRegNo|$08}} controls the mapping of chip channels to stereo channels and {{NextRegNo|$09}} can be used to enable "mono" output per chip.

Once a sound chip is selected, {{PortNo|$FFFD}} also selects the active register on that chip. {{PortNo|$BFFD}} then allows it to be read or written.

{{NextRegNo|$06}} controls audio chip mode.

= AY-3-8912 layout =
The 3 AY-3-8912 chips have the following register layout:

{| class="wikitable"
! Register !! Function
|-
| 0 || Channel A Fine Tune
|-
| 1 || Channel A Coarse Tune (4 bits)
|-
| 2 || Channel B Fine Tune
|-
| 3 || Channel B Coarse Tune (4 bits)
|-
| 4 || Channel C Fine Tune
|-
| 5 || Channel C Coarse Tune (4 bits)
|-
| 6 || Noise Period (5 bits)
|-
| 7 || Tone enable flags.

Bits 0-2 enable tone on channels A, B, C respectively, but are inverted - 0 is enabled.

Bits 3-5 enable noise on A, B, C are are likewise inverted.
|-
| 8 || Channel A amplitude.

Bits 0-3 set the fixed amplitude which is used if bit 4 is 0. If bit 4 is 1, the envelope generator is used instead, and bits 0-3 are ignored.
|-
| 9 || Channel B amplitude, same as above.
|-
| 10 || Channel C amplitude, same as above.
|-
| 11 || Envelope period fine.
|-
| 12 || Envelope period coarse.
|-
| 13 || Envelope shape.
Bits 0-3 alter the behaviour of the envelope generator:
Bit 0: "Hold"; If 1 the envelope generator performs one cycle then holds at the end value. If 0, it cycles continuously.

Bit 1: "Alternate"; If 1 the envelope generator alters direction after each cycle. If 0, it resets after each cycle. If Hold is set, this instead chooses if the value held is the final value (0) or the initial value (1).

Bit 2: "Attack"; if 1 the generator counts up. If 0 the generator counts down.

Bit 3: "Continue"; if 0, the envelope generator performs one cycle then drops amplitude to 0 and stays there, overriding Hold. If 1, Hold is followed.
|}

AY I/O registers 14 and 15 are not implemented on the Next, so bit-banged software written to use RS-232 and AUX ports on the Amstrad Spectrum models is not supported. The Next has a separate high-speed hardware [[UART]], which can be connected to the [[ESP8266-01]] wifi module or a wired RS-232 cable. The UART is interfaced through the {{PortNo|$133B}} and {{PortNo|$143B}} ports.

Turbo Sound Next

2025-05-24T19:05:30Z

Em00k:

Turbo Sound Next is the audio system integrated on the Spectrum Next. It features 3 AY-3-8912 sound chips as used in the Spectrum.

A MOS 6581 (SID), as used on the Commodore 64, was experimentally added to the FPGA during development but it was later removed due to the large amount of space it takes up (it is 4 times as big as an AY).

For information on playing back PT3 files, have a look here : [[https://wiki.specnext.dev/Code:PT3 Various PT3 replay methods]]

= Chip Selection =
{{PortNo|$FFFD}} controls the selected chip and enables and disables stereo channels per chip. {{NextRegNo|$08}} controls the mapping of chip channels to stereo channels and {{NextRegNo|$09}} can be used to enable "mono" output per chip.

Once a sound chip is selected, {{PortNo|$FFFD}} also selects the active register on that chip. {{PortNo|$BFFD}} then allows it to be read or written.

{{NextRegNo|$06}} controls audio chip mode.

= AY-3-8912 layout =
The 3 AY-3-8912 chips have the following register layout:

{| class="wikitable"
! Register !! Function
|-
| 0 || Channel A Fine Tune
|-
| 1 || Channel A Coarse Tune (4 bits)
|-
| 2 || Channel B Fine Tune
|-
| 3 || Channel B Coarse Tune (4 bits)
|-
| 4 || Channel C Fine Tune
|-
| 5 || Channel C Coarse Tune (4 bits)
|-
| 6 || Noise Period (5 bits)
|-
| 7 || Tone enable flags. Bits 0-2 enable tone on channels A, B, C respectively, but are inverted - 0 is enabled. Bits 3-5 enable noise on A, B, C are are likewise inverted.
|-
| 8 || Channel A amplitude. Bits 0-3 set the fixed amplitude which is used if bit 4 is 0. If bit 4 is 1, the envelope generator is used instead, and bits 0-3 are ignored.
|-
| 9 || Channel B amplitude, same as above.
|-
| 10 || Channel C amplitude, same as above.
|-
| 11 || Envelope period fine.
|-
| 12 || Envelope period coarse.
|-
| 13 || Envelope shape. Bits 0-3 alter the behaviour of the envelope generator:
Bit 0: "Hold"; If 1 the envelope generator performs one cycle then holds at the end value. If 0, it cycles continuously.

Bit 1: "Alternate"; If 1 the envelope generator alters direction after each cycle. If 0, it resets after each cycle. If Hold is set, this instead chooses if the value held is the final value (0) or the initial value (1).

Bit 2: "Attack"; if 1 the generator counts up. If 0 the generator counts down.

Bit 3: "Continue"; if 0, the envelope generator performs one cycle then drops amplitude to 0 and stays there, overriding Hold. If 1, Hold is followed.
|}

AY I/O registers 14 and 15 are not implemented on the Next, so bit-banged software written to use RS-232 and AUX ports on the Amstrad Spectrum models is not supported. The Next has a separate high-speed hardware [[UART]], which can be connected to the [[ESP8266-01]] wifi module or a wired RS-232 cable. The UART is interfaced through the {{PortNo|$133B}} and {{PortNo|$143B}} ports.

Turbo Sound Next

2025-05-24T19:04:45Z

Em00k:

Turbo Sound Next is the audio system integrated on the Spectrum Next. It features 3 AY-3-8912 sound chips as used in the Spectrum.

A MOS 6581 (SID), as used on the Commodore 64, was experimentally added to the FPGA during development but it was later removed due to the large amount of space it takes up (it is 4 times as big as an AY).

For information on playing back PT3 files, have a look here : [[https://wiki.specnext.dev/Code:PT3 |Various PT3 replay methods]]

= Chip Selection =
{{PortNo|$FFFD}} controls the selected chip and enables and disables stereo channels per chip. {{NextRegNo|$08}} controls the mapping of chip channels to stereo channels and {{NextRegNo|$09}} can be used to enable "mono" output per chip.

Once a sound chip is selected, {{PortNo|$FFFD}} also selects the active register on that chip. {{PortNo|$BFFD}} then allows it to be read or written.

{{NextRegNo|$06}} controls audio chip mode.

= AY-3-8912 layout =
The 3 AY-3-8912 chips have the following register layout:

{| class="wikitable"
! Register !! Function
|-
| 0 || Channel A Fine Tune
|-
| 1 || Channel A Coarse Tune (4 bits)
|-
| 2 || Channel B Fine Tune
|-
| 3 || Channel B Coarse Tune (4 bits)
|-
| 4 || Channel C Fine Tune
|-
| 5 || Channel C Coarse Tune (4 bits)
|-
| 6 || Noise Period (5 bits)
|-
| 7 || Tone enable flags. Bits 0-2 enable tone on channels A, B, C respectively, but are inverted - 0 is enabled. Bits 3-5 enable noise on A, B, C are are likewise inverted.
|-
| 8 || Channel A amplitude. Bits 0-3 set the fixed amplitude which is used if bit 4 is 0. If bit 4 is 1, the envelope generator is used instead, and bits 0-3 are ignored.
|-
| 9 || Channel B amplitude, same as above.
|-
| 10 || Channel C amplitude, same as above.
|-
| 11 || Envelope period fine.
|-
| 12 || Envelope period coarse.
|-
| 13 || Envelope shape. Bits 0-3 alter the behaviour of the envelope generator:
Bit 0: "Hold"; If 1 the envelope generator performs one cycle then holds at the end value. If 0, it cycles continuously.

Bit 1: "Alternate"; If 1 the envelope generator alters direction after each cycle. If 0, it resets after each cycle. If Hold is set, this instead chooses if the value held is the final value (0) or the initial value (1).

Bit 2: "Attack"; if 1 the generator counts up. If 0 the generator counts down.

Bit 3: "Continue"; if 0, the envelope generator performs one cycle then drops amplitude to 0 and stays there, overriding Hold. If 1, Hold is followed.
|}

AY I/O registers 14 and 15 are not implemented on the Next, so bit-banged software written to use RS-232 and AUX ports on the Amstrad Spectrum models is not supported. The Next has a separate high-speed hardware [[UART]], which can be connected to the [[ESP8266-01]] wifi module or a wired RS-232 cable. The UART is interfaced through the {{PortNo|$133B}} and {{PortNo|$143B}} ports.

Turbo Sound Next

2025-05-24T19:03:41Z

Em00k:

Turbo Sound Next is the audio system integrated on the Spectrum Next. It features 3 AY-3-8912 sound chips as used in the Spectrum.

A MOS 6581 (SID), as used on the Commodore 64, was experimentally added to the FPGA during development but it was later removed due to the large amount of space it takes up (it is 4 times as big as an AY).

For information on playing back PT3 files, have a look here : [[https://wiki.specnext.dev/Code:PT3|Various PT3 replay methods]]

= Chip Selection =
{{PortNo|$FFFD}} controls the selected chip and enables and disables stereo channels per chip. {{NextRegNo|$08}} controls the mapping of chip channels to stereo channels and {{NextRegNo|$09}} can be used to enable "mono" output per chip.

Once a sound chip is selected, {{PortNo|$FFFD}} also selects the active register on that chip. {{PortNo|$BFFD}} then allows it to be read or written.

{{NextRegNo|$06}} controls audio chip mode.

= AY-3-8912 layout =
The 3 AY-3-8912 chips have the following register layout:

{| class="wikitable"
! Register !! Function
|-
| 0 || Channel A Fine Tune
|-
| 1 || Channel A Coarse Tune (4 bits)
|-
| 2 || Channel B Fine Tune
|-
| 3 || Channel B Coarse Tune (4 bits)
|-
| 4 || Channel C Fine Tune
|-
| 5 || Channel C Coarse Tune (4 bits)
|-
| 6 || Noise Period (5 bits)
|-
| 7 || Tone enable flags. Bits 0-2 enable tone on channels A, B, C respectively, but are inverted - 0 is enabled. Bits 3-5 enable noise on A, B, C are are likewise inverted.
|-
| 8 || Channel A amplitude. Bits 0-3 set the fixed amplitude which is used if bit 4 is 0. If bit 4 is 1, the envelope generator is used instead, and bits 0-3 are ignored.
|-
| 9 || Channel B amplitude, same as above.
|-
| 10 || Channel C amplitude, same as above.
|-
| 11 || Envelope period fine.
|-
| 12 || Envelope period coarse.
|-
| 13 || Envelope shape. Bits 0-3 alter the behaviour of the envelope generator:
Bit 0: "Hold"; If 1 the envelope generator performs one cycle then holds at the end value. If 0, it cycles continuously.

Bit 1: "Alternate"; If 1 the envelope generator alters direction after each cycle. If 0, it resets after each cycle. If Hold is set, this instead chooses if the value held is the final value (0) or the initial value (1).

Bit 2: "Attack"; if 1 the generator counts up. If 0 the generator counts down.

Bit 3: "Continue"; if 0, the envelope generator performs one cycle then drops amplitude to 0 and stays there, overriding Hold. If 1, Hold is followed.
|}

AY I/O registers 14 and 15 are not implemented on the Next, so bit-banged software written to use RS-232 and AUX ports on the Amstrad Spectrum models is not supported. The Next has a separate high-speed hardware [[UART]], which can be connected to the [[ESP8266-01]] wifi module or a wired RS-232 cable. The UART is interfaced through the {{PortNo|$133B}} and {{PortNo|$143B}} ports.

Turbo Sound Next

2025-05-24T19:03:19Z

Em00k:

Turbo Sound Next is the audio system integrated on the Spectrum Next. It features 3 AY-3-8912 sound chips as used in the Spectrum.

A MOS 6581 (SID), as used on the Commodore 64, was experimentally added to the FPGA during development but it was later removed due to the large amount of space it takes up (it is 4 times as big as an AY).

For information on playing back PT3 files, have a look here : [[https://wiki.specnext.dev/Code:PT3|Various PT3 replay methods]]

= Chip Selection =
{{PortNo|$FFFD}} controls the selected chip and enables and disables stereo channels per chip. {{NextRegNo|$08}} controls the mapping of chip channels to stereo channels and {{NextRegNo|$09}} can be used to enable "mono" output per chip.

Once a sound chip is selected, {{PortNo|$FFFD}} also selects the active register on that chip. {{PortNo|$BFFD}} then allows it to be read or written.

{{NextRegNo|$06}} controls audio chip mode.

= AY-3-8912 layout =
The 3 AY-3-8912 chips have the following register layout:

{| class="wikitable"
! Register !! Function
|-
| 0 || Channel A Fine Tune
|-
| 1 || Channel A Coarse Tune (4 bits)
|-
| 2 || Channel B Fine Tune
|-
| 3 || Channel B Coarse Tune (4 bits)
|-
| 4 || Channel C Fine Tune
|-
| 5 || Channel C Coarse Tune (4 bits)
|-
| 6 || Noise Period (5 bits)
|-
| 7 || Tone enable flags. Bits 0-2 enable tone on channels A, B, C respectively, but are inverted - 0 is enabled. Bits 3-5 enable noise on A, B, C are are likewise inverted.
|-
| 8 || Channel A amplitude. Bits 0-3 set the fixed amplitude which is used if bit 4 is 0. If bit 4 is 1, the envelope generator is used instead, and bits 0-3 are ignored.
|-
| 9 || Channel B amplitude, same as above.
|-
| 10 || Channel C amplitude, same as above.
|-
| 11 || Envelope period fine.
|-
| 12 || Envelope period coarse.
|-
| 13 || Envelope shape. Bits 0-3 alter the behavior of the envelope generator:
Bit 0: "Hold"; If 1 the envelope generator performs one cycle then holds at the end value. If 0, it cycles continuously.

Bit 1: "Alternate"; If 1 the envelope generator alters direction after each cycle. If 0, it resets after each cycle. If Hold is set, this instead chooses if the value held is the final value (0) or the initial value (1).

Bit 2: "Attack"; if 1 the generator counts up. If 0 the generator counts down.

Bit 3: "Continue"; if 0, the envelope generator performs one cycle then drops amplitude to 0 and stays there, overriding Hold. If 1, Hold is followed.
|}

AY I/O registers 14 and 15 are not implemented on the Next, so bit-banged software written to use RS-232 and AUX ports on the Amstrad Spectrum models is not supported. The Next has a separate high-speed hardware [[UART]], which can be connected to the [[ESP8266-01]] wifi module or a wired RS-232 cable. The UART is interfaced through the {{PortNo|$133B}} and {{PortNo|$143B}} ports.

Code:PT3

2025-05-24T17:03:32Z

Em00k:

Playing back .PT3 Audio Files

=== Assembler ===
* [[Code:PT3:sjasmplus|sjasmplus]]
* https://github.com/em00k/3ch-6ch-PT3-player-ZXNext
=== BASIC ===
* [[Dot:playpt3|DOT]]
* [[Code:PT3:BASIC|BASIC Driver]]
* [[Code:PT3:Boriel|Boriel]]

=== C ===
* [[Code:PT3:Z88DK|Z88DK]]

FAQ

2025-04-15T00:02:02Z

Em00k: /* How do I connect to Wi-Fi? */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wi-Fi? ==
The Next's ESP can only connect to 2.4Ghz Wi-Fi networks, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

<code>AT+CIFSR</code>

This should return your IP. If you are still having issues, confirm the network is 2.4Ghz, and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches, enter a game search term and press return. If you see results wifi is working.

If you continue to have issues confirm the ESP baud rate, from the command line :

<code>.espbaud -dR </code>

This will >Reset and try to >detect the current speed. A message saying "Resetting ESP", then a baud rate test will begin, once the program has finished, a success would look like this :

<code>ESP reports 115273
Setting uart to 115273</code>

This usually confirms the correct speed has been negotiated. Now run .uart and run the command above and see if you get a response.
Another useful AT command to run is :

<code>AT+GMR </code>

This will report your current ESP firmware. FW v1.2.0.0 is the version shipped with both KS models. The reliability of this differs in opinion and some people have updated to newer versions 1.6.0.0 and 1.7.6.0 reporting less oddities and overall more stable operation. Owner's must understand the risks involved when updating fw as it is possible to brick your ESP and for KS2 models, the ESP is soldered to the motherboard making replacing more complicated. FW updates can be done using the .espupdate dotcommand supplied on the official distro and heading over [https://github.com/Threetwosevensixseven/espupdate/wiki/Update-ESP-Firmware-From-ZX-Spectrum-Next here for more information].

Furthur information on the ESP and AT commands is [[ESP8266-01|linked here]]

[[File:Uart-fw.png|frameless]]

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

FAQ

2025-04-14T23:53:05Z

Em00k: /* How do I connect to Wi-Fi? */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wi-Fi? ==
The Next's ESP can only connect to 2.4Ghz Wi-Fi networks, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

<code>AT+CIFSR</code>

This should return your IP. If you are still having issues, confirm the network is 2.4Ghz, and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches, enter a game search term and press return. If you see results wifi is working.

If you continue to have issues confirm the ESP baud rate, from the command line :

<code>.espbaud -dR </code>

This will >Reset and try to >detect the current speed. A message saying "Resetting ESP", then a baud rate test will begin, once the program has finished, a success would look like this :

<code>ESP reports 115273
Setting uart to 115273</code>

This usually confirms the correct speed has been negotiated. Now run .uart and run the command above and see if you get a response.
Another useful AT command to run is :

<code>AT+GMR </code>

Furthur information on the ESP and AT commands is [[ESP8266-01|linked here]]

This will report your current ESP firmware. FW v1.2.0.0 is the version shipped with both KS models. The reliability of this differs in opinion and some people have updated to newer versions 1.6.0.0 and 1.7.6.0 reporting less oddities and overall more stable operation. Owner's must understand the risks involved when updating fw as it is possible to brick your ESP and for KS2 models, the ESP is soldered to the motherboard making replacing more complicated. FW updates can be done using the .espupdate dotcommand supplied on the official distro and heading over [https://github.com/Threetwosevensixseven/espupdate/wiki/Update-ESP-Firmware-From-ZX-Spectrum-Next here for more information].

[[File:Uart-fw.png|frameless]]

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

FAQ

2025-04-14T23:50:53Z

Em00k: /* How do I connect to Wi-Fi? */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wi-Fi? ==
The Next's ESP can only connect to 2.4Ghz Wi-Fi networks, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

<code>AT+CIFSR</code>

This should return your IP. If you are still having issues, confirm the network is 2.4Ghz, and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches, enter a game search term and press return. If you see results wifi is working.

If you continue to have issues confirm the ESP baud rate, from the command line :

<code>.espbaud -dR </code>

This will >Reset and try to >detect the current speed. A message saying "Resetting ESP", then a baud rate test will begin, once the program has finished, a success would look like this :

<code>ESP reports 115273
Setting uart to 115273</code>

This usually confirms the correct speed has been negotiated. Now run .uart and run the command above and see if you get a response.
Another useful AT command to run is :

<code>AT+GMR </code>

Furthur information on the ESP and AT commands is [[ESP8266-01|linked here]]

This will report your current ESP firmware. FW v1.2.0.0 is the version shipped with both KS models. The reliability of this differs in opinion and some people have updated to newer versions 1.6.0.0 and 1.7.6.0 reporting less oddities and overall more stable operation. Owner's must understand the risks involved when updating fw as it is possible to brick your ESP and for KS2 models, the ESP is soldered to the motherboard making replacing more complicated. FW updates can be done using the .espupdate dotcommand supplied on the official distro and heading over [https://github.com/Threetwosevensixseven/espupdate/wiki/Update-ESP-Firmware-From-ZX-Spectrum-Next here for more information].

[[File:Uart-fw.png|thumb]]

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

FAQ

2025-04-14T23:46:43Z

Em00k: /* How do I connect to Wi-Fi? */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wi-Fi? ==
The Next's ESP can only connect to 2.4Ghz Wi-Fi networks, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

<code>AT+CIFSR</code>

This should return your IP. If you are still having issues, confirm the network is 2.4Ghz, and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches, enter a game search term and press return. If you see results wifi is working.

If you continue to have issues confirm the ESP baud rate, from the command line :

<code>.espbaud -dR </code>

This will >Reset and try to >detect the current speed. A message saying "Resetting ESP", then a baud rate test will begin, once the program has finished, it will either say :

<code>ESP reports 115273
Setting uart to 115273</code>

This usually confirms the correct speed has been negotiated. Now run .uart and run the command above and see if you get a response.
A comprehensive overview of the ESP and AT commands can be found here [[ESP8266-01]] Another useful AT command to run is :

<code>AT+GMR </code>

This will report your current ESP firmware. FW v1.2.0.0 is the version shipped with both KS models. The reliability of this differs in opinion and some people have updated to newer versions 1.6.0.0 and 1.7.6.0 reporting less oddities and overall more stable operation. Owner's must understand the risks involved when updating fw as it is possible to brick your ESP and for KS2 models, the ESP is soldered to the motherboard making replacing more complicated. FW updates can be done using the .espupdate dotcommand supplied on the official distro and heading over [https://github.com/Threetwosevensixseven/espupdate/wiki/Update-ESP-Firmware-From-ZX-Spectrum-Next here for more information].

[[File:Uart-fw.png|thumb]]

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

FAQ

2025-04-14T23:45:01Z

Em00k: /* How do I connect to Wifi? */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wi-Fi? ==
You can connect to a 2.4Ghz Wi-Fi network, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

<code>AT+CIFSR</code>

This should return your IP. If you are still having issues, confirm the network is 2.4Ghz, and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches, enter a game search term and press return. If you see results wifi is working.

If you continue to have issues confirm the ESP baud rate, from the command line :

<code>.espbaud -dR </code>

This will >Reset and try to >detect the current speed. A message saying "Resetting ESP", then a baud rate test will begin, once the program has finished, it will either say :

<code>ESP reports 115273
Setting uart to 115273</code>

This usually confirms the correct speed has been negotiated. Now run .uart and run the command above and see if you get a response.
A comprehensive overview of the ESP and AT commands can be found here [[ESP8266-01]] Another useful AT command to run is :

<code>AT+GMR </code>

This will report your current ESP firmware. FW v1.2.0.0 is the version shipped with both KS models. The reliability of this differs in opinion and some people have updated to newer versions 1.6.0.0 and 1.7.6.0 reporting less oddities and overall more stable operation. Owner's must understand the risks involved when updating fw as it is possible to brick your ESP and for KS2 models, the ESP is soldered to the motherboard making replacing more complicated. FW updates can be done using the .espupdate dotcommand supplied on the official distro and heading over [https://github.com/Threetwosevensixseven/espupdate/wiki/Update-ESP-Firmware-From-ZX-Spectrum-Next here for more information].

[[File:Uart-fw.png|thumb]]

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

File:Uart-fw.png

2025-04-14T23:10:05Z

Em00k:

AT version 1.7.6.0 connected at 115,200.

NextBuildStudio:Main Page

2025-04-12T03:24:06Z

Em00k: /* Tile Operations */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

There are two types when referring to tile maps. Software tiles are drawn by copying tiles from preloaded banks to the Layer2 graphics screen. Hardware tile maps use a tile system similar found on retro consoles and computers such as the Commodore 64, Nintendo NES and Sega MegaDrive. Below uses software tiles.

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

For details on using the hardware tile map see the [Hardware Tilemap] section.

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T03:13:23Z

Em00k: /* Setup Instructions */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T03:12:52Z

Em00k: /* Project Structure */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder.

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:49:17Z

Em00k: /* Drawing a Sprite */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768

#define NEX
#include <nextlib.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Upload 64 sprites from bank 34
InitSprites2(64, 0, 34, 0)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:47:21Z

Em00k: /* SD Card Access */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="vb">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:46:55Z

Em00k: /* Preprocessor Options */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your `.bas` file:

{| class="wikitable"
! Option !! Description !! Default
|-
| <code>!org=nn</code> || Program start address (24576–65530) || 32768
|-
| <code>!heap=nn</code> || Heap size in bytes || 2048
|-
| <code>!opt=n</code> || Optimization value (0–4) || 4
|-
| <code>!bmp=filename</code> || BMP loading screen for NEX || None
|-
| <code>!copy=filename</code> || Copy NEX file to specified path || None
|-
| <code>!noemu</code> || Do not launch emulator after compilation || Emulator launches
|-
| <code>!asm</code> || Produce ASM output only || NEX file created
|-
| <code>!nosys</code> || Do not include system variables || Include sysvars
|-
| <code>!nosp</code> || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:45:37Z

Em00k: /* Creating Your First Project */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:42:11Z

Em00k: /* Creating Your First Project */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new folder in the Sources directory, then a .bas file inside the new folder.
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

PAPER 0 : INK 7 : CLS

PRINT "Congratulations!"

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T02:40:10Z

Em00k: /* NextBuild v8 */

= NextBuild v8 =
[[File:VSCode With NextBuild.png|thumb|Right|NextBuild]]

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with [https://zxbasic.readthedocs.io/en/docs/ Boriel's ZX Basic compiler] for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Cspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is [https://code.visualstudio.com/ Visual Studio Code], with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* [https://code.visualstudio.com/ Visual Studio Code] (recommended IDE)
* [https://github.com/em00k/NextBuild NextBuild tools package] (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

When launching Visual Studio Code proceed to open a project and select the "Source" directory inside the NextBuildvN folder. A video demonstrating how to correctly setup up is available here : https://www.youtube.com/watch?v=kF_jfE7mAvg

== Creating Your First Project ==

# Create a new .bas file in the Sources directory
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

File:VSCode With NextBuild.png

2025-04-12T02:31:59Z

Em00k:

Image showing Visual Studio Code with the NextBuild extension

NextBuildStudio:Main Page

2025-04-12T01:42:53Z

Em00k: /* NOTE : This documentation is still in progress */

= NextBuild v8 =

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with Boriel's ZX Basic compiler for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file. At the heart of the suite is the NextBuild Library, which facilitates communication directly with the ZX Nexts hardware through optimized assembly routines. Combine this ZX Basic compiler's compiled code produces blazingly fast professional results.

Code is executed with Aspect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The IDE strongly recommended is Visual Studio Code, with setup being straightforward through automatically configured build scripts, tasks, and extensions. NextBuild has been designed to integrate tightly with VSCode. NextBuild will also operate faultlessly with AI editors such as Cursor.

Note, the ZX Basic has been tweaked slightly to work with nicely with the Next's HW. Special conditions are put in place to make sure interrupts or stack locations interfere when paging memory banks or using additional graphics modes. If the nextlib library is used outside the NextBuild suite, it is likely that you will experience issues.

== Setup Instructions ==

=== Requirements ===

* Visual Studio Code (recommended IDE)
* NextBuild tools package (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

== Creating Your First Project ==

# Create a new .bas file in the Sources directory
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T01:33:33Z

Em00k: /* Debugging */

= NextBuild v8 =

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with Boriel's ZX Basic compiler for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file.

Code is executed with CSpect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The preferred IDE is Visual Studio Code, with setup being straightforward through automatically configured build scripts, tasks, and extensions.

== Setup Instructions ==

=== Requirements ===

* Visual Studio Code (recommended IDE)
* NextBuild tools package (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

== Creating Your First Project ==

# Create a new .bas file in the Sources directory
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BBREAK macros in your code or BREAK inside an asm block

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NextBuildStudio:Main Page

2025-04-12T01:31:32Z

Em00k: /* Additional Resources */

= NextBuild v8 =

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with Boriel's ZX Basic compiler for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file.

Code is executed with CSpect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The preferred IDE is Visual Studio Code, with setup being straightforward through automatically configured build scripts, tasks, and extensions.

== Setup Instructions ==

=== Requirements ===

* Visual Studio Code (recommended IDE)
* NextBuild tools package (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

== Creating Your First Project ==

# Create a new .bas file in the Sources directory
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BREAK or BBREAK macros in your code

== Additional Resources ==

* Full ZX Basic Compiler command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* NextBuild Github [https://github.com/em00k/NextBuild]
* NextBuild command lookup [https://zxnext.uk/docs/]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

NexTest

2025-04-12T01:07:40Z

Em00k: /* Manual Tests */

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

[[File:Nextest Joystick Detail.png|above|Joystick detail]]

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-12T01:07:03Z

Em00k: /* Kempston Joystick */

NextBuild Topics

2025-04-12T00:42:47Z

Em00k: Created page with "= NextBuild Topics = This page serves as a central hub for all NextBuild-related topics. Each section below links to detailed articles about specific aspects of developing fo..."

= NextBuild Topics =

This page serves as a central hub for all NextBuild-related topics. Each section below links to detailed articles about specific aspects of developing for the ZX Spectrum Next using NextBuild.

== Getting Started ==

* [[NextBuild Installation and Setup]]
* [[Creating Your First NextBuild Project]]
* [[NextBuild Preprocessor Options]]
* [[Building and Running NextBuild Projects]]
* [[VSCode Integration and Tasks]]

== Graphics ==

* [[Layer 2 Graphics in NextBuild]]
* [[Sprites and Animation]]
* [[Tile-Based Graphics]]
* [[Palette Management]]
* [[Drawing Text in Layer 2]]
* [[Advanced Drawing Techniques]]

== Audio ==

* [[Sound Effects with AYFX]]
* [[Music with PT3 Format]]
* [[Setting Up Interrupt Mode 2 for Audio]]
* [[NextSID Audio Engine]]
* [[Mixing Music and Sound Effects]]

== Input and Control ==

* [[Keyboard Input in NextBuild]]
* [[Joystick and Gamepad Support]]
* [[Mouse Input]]
* [[Creating Responsive Controls]]

== Memory Management ==

* [[Understanding MMU and Banking]]
* [[Memory Organization on the ZX Spectrum Next]]
* [[Efficient Memory Usage]]
* [[Working with Multiple Banks]]

== File Operations ==

* [[Loading and Saving to SD Card]]
* [[Working with NEX Files]]
* [[File Formats and Conversions]]
* [[Asset Management]]

== Advanced Topics ==

* [[Copper Effects and Raster Interrupts]]
* [[Optimizing NextBuild Code]]
* [[Assembly Language Integration]]
* [[DMA Operations]]
* [[NextBuild Debugging Techniques]]

== Game Development ==

* [[Game Loop Structure]]
* [[Collision Detection]]
* [[Scrolling Backgrounds]]
* [[Sprite-Based Animation]]
* [[Game State Management]]
* [[Example Game Projects]]

== Tools and Utilities ==

* [[NextBuild Command Line Tools]]
* [[Asset Creation Tools]]
* [[Sprite and Tile Editors]]
* [[CSpect Emulator Features]]
* [[Converting Existing Assets]]

== Reference ==

* [[NextLib Function Reference]]
* [[ZX Spectrum Next Hardware Registers]]
* [[NextBuild Preprocessor Reference]]
* [[Common Error Messages and Solutions]]

== Tutorials ==

* [[Creating a Simple Platform Game]]
* [[Building a Scrolling Shooter]]
* [[Text Adventure Development]]
* [[Creating Special Effects]]
* [[Optimizing Performance]]

NextBuildStudio:Main Page

2025-04-12T00:35:57Z

Em00k:

= NextBuild v8 =

== Introduction ==

=== NOTE : This documentation is still in progress ===

NextBuild is a collection of tools and libraries which works with Boriel's ZX Basic compiler for working with the ZX Spectrum Next. Version 8 introduces significant changes, including NEX file generation that contains all your assets in a single file.

Code is executed with CSpect emulator written by Mike Dailly [https://mdf200.itch.io/cspect].

The preferred IDE is Visual Studio Code, with setup being straightforward through automatically configured build scripts, tasks, and extensions.

== Setup Instructions ==

=== Requirements ===

* Visual Studio Code (recommended IDE)
* NextBuild tools package (includes Boriel ZX Basic, CSpect emulator, and NextBuild scripts)

=== Installation ===

# Clone or download the NextBuild repository
# Open the project folder in Visual Studio Code
# Install recommended extensions:
#* em00k.nextbuild
#* eliverlara.andromeda
#* maziac.nex-fileviewer
#* maziac.asm-code-lens
#* alefragnani.bookmarks
#* commandvariable.dateTime

== Project Structure ==

<pre>
/NextBuild
├── zxbasic/ (Boriel ZX Basic compiler)
├── Emu/ (CSpect emulator)
│ └── CSpect/
├── Scripts/ (NextBuild python scripts)
├── Sources/ (Main sources folder)
│ ├── examples/ (Example code)
└───└── data/ (Assets: sprites, sounds, etc.)
</pre>

== Creating Your First Project ==

# Create a new .bas file in the Sources directory
# Add the following template:

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
' Main loop
loop
</syntaxhighlight>

# Press Ctrl+Shift+B or select "Run Build Task" from the Terminal menu to compile

== Preprocessor Options ==

These options are set at the top of your .bas file:

{| class="wikitable"
! Option !! Description !! Default
|-
| '!org=nn || Program start address (24576-65530) || 32768
|-
| '!heap=nn || Heap size in bytes || 2048
|-
| '!opt=n || Optimization value (0-4) || 4
|-
| '!bmp=filename || BMP loading screen for NEX || None
|-
| '!copy=filename || Copy NEX file to specified path || None
|-
| '!noemu || Do not launch emulator after compilation || Emulator launches
|-
| '!asm || Produce ASM output only || NEX file created
|-
| '!nosys || Do not include system variables || Include sysvars
|-
| '!nosp || Do not set up stack pointer || Set up SP
|}

== NextLib Library ==

NextLib provides functions to access ZX Spectrum Next hardware features.

=== SD Card Access ===

<syntaxhighlight lang="basic">
' Load data from SD card to a memory bank
LoadSDBank(filename$, address, size, offset, bank)
' Load from SD to memory address
LoadSD(filename$, address, size, offset)
' Save from memory to SD card
SaveSD(filename$, address, size)
' Load a BMP file to Layer 2
LoadBMP(filename$)
</syntaxhighlight>

=== Layer 2 Graphics ===

<syntaxhighlight lang="basic">
' Enable/disable Layer 2
ShowLayer2(n) ' 0=off, 1=on
' Clear Layer 2 with color
CLS256(color)
' Scroll Layer 2
ScrollLayer(x, y)
' Set clipping regions
ClipLayer2(x1, x2, y1, y2)
ClipLayerULA(x1, x2, y1, y2)
ClipLayerTile(x1, x2, y1, y2)
ClipSprite(x1, x2, y1, y2)
</syntaxhighlight>

=== Tile Operations ===

<syntaxhighlight lang="basic">
' Draw a 16x16 tile from bank
DoTileBank16(x, y, tile_number, bank_number)
' Draw an 8x8 tile from bank
DoTileBank8(x, y, tile_number, bank_number)
' Draw a tile in 320x256 mode
FDoTileBank8(y, x, tile_number, bank_number)
FDoTileBank16(y, x, tile_number, bank_number)
</syntaxhighlight>

=== Pixel Operations ===

<syntaxhighlight lang="basic">
' Plot a pixel in Layer 2 (256x192)
PlotL2(x, y, color)
' Plot a pixel in Layer 2 (320x256)
FPlotL2(x, y, color)
' Draw text on Layer 2
L2Text(x, y, string$, bank, mask)
FL2Text(x, y, string$, bank)
</syntaxhighlight>

=== Palette Management ===

<syntaxhighlight lang="basic">
' Upload a palette
PalUpload(address, colors_count, offset, bank)
</syntaxhighlight>

=== Sprite Operations ===

<syntaxhighlight lang="basic">
' Initialize sprites
InitSprites(total, sprite_address)
InitSprites2(total, sprite_address, bank, sprite_offset)
' Update sprite parameters
UpdateSprite(x, y, sprite_id, pattern, mirror_flip, anchor)
' Remove a sprite
RemoveSprite(sprite_id, visible)
</syntaxhighlight>

=== Memory Management ===

<syntaxhighlight lang="basic">
' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)
</syntaxhighlight>

=== Timing and Synchronization ===

<syntaxhighlight lang="basic">
' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()
</syntaxhighlight>

=== Music and Sound Effects ===

<syntaxhighlight lang="basic">
' Initialize music player
InitMusic(player_bank, music_bank, music_offset)
' Initialize sound effects
InitSFX(bank)
' Set up interrupt mode
SetUpIM()
' Control sound
EnableSFX
DisableSFX
EnableMusic
DisableMusic
' Play a sound effect
PlaySFX(effect_number)
</syntaxhighlight>

== Memory Management ==

=== MMU Slots ===

The ZX Spectrum Next divides its memory into 8KB slots that can be mapped to different banks:

{| class="wikitable"
! Area !! Address Range !! Default !! Description
|-
| $0000-$1fff || Slot 0 || ROM (255) || Normally ROM. Writes mappable by layer 2. IRQ and NMI routines here.
|-
| $2000-$3fff || Slot 1 || ROM (255) || Normally ROM. Writes mapped by Layer 2.
|-
| $4000-$5fff || Slot 2 || 10 || Normally used for normal/shadow ULA screen.
|-
| $6000-$7fff || Slot 3 || 11 || Timex ULA extended attribute/graphics area.
|-
| $8000-$9fff || Slot 4 || 4 || Free RAM.
|-
| $a000-$bfff || Slot 5 || 5 || Free RAM.
|-
| $c000-$dfff || Slot 6 || 0 || Free RAM. Only this area is remappable by 128 memory management.
|-
| $e000-$ffff || Slot 7 || 1 || Free RAM. Only this area is remappable by 128 memory management.
|}

=== RAM Banks ===

<pre>
16kb 8kb
8-15 16-31 $060000-$07ffff 128K Extra RAM
16-47 32-95 $080000-$0fffff 512K 1st extra IC RAM (available on unexpanded Next)
48-79 96-159 $100000-$17ffff 512K 2nd extra IC RAM (only available on expanded Next)
80-111 160-223 $180000-$1fffff 512K 3rd extra IC RAM (only available on expanded Next)
</pre>

== NEX File Format ==

The NEX file is a container that holds your program and all assets in a single file. It is created automatically during the build process.

=== Configuration Options ===

The NEX file configuration is generated from preprocessor directives in your source file:

<syntaxhighlight lang="basic">
'!org=32768 ' Program start address
'!bmp=intro.bmp ' Loading screen
</syntaxhighlight>

== Extending With Interrupt Mode 2 ==

For advanced applications requiring sound and music, you can enable Interrupt Mode 2:

<syntaxhighlight lang="basic">
#define IM2
#include <nextlib.bas>
#include <nextlib_ints.bas>

InitSFX(36) ' SFX bank
InitMusic(38, 39, 0000) ' Player bank, music bank, offset
SetUpIM() ' Set up IM2
EnableSFX ' Enable SFX playback
EnableMusic ' Enable music playback
</syntaxhighlight>

== Examples ==

=== Drawing a Sprite ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>
#include <keys.bas>

' Load sprites from SD card to bank 34
LoadSDBank("testsprites.spr", 0, 0, 0, 34)

' Set up banks and initialize sprites
asm
nextreg $56, 34
nextreg $57, 35
end asm

InitSprites2(64, $c000, 34)

' Main loop
do
' Update sprite at position 100,100
UpdateSprite(100, 100, 0, 0, 0, 128)
WaitRetrace(1)
loop
</syntaxhighlight>

=== Tile-Based Game Screen ===

<syntaxhighlight lang="basic">
'!org=32768
'!heap=2048

#define NEX
#include <nextlib.bas>

' Load tile data
LoadSDBank("tiles.spr", 0, 0, 0, 36)

' Clear Layer 2
CLS256(0)
ShowLayer2(1)

' Draw a 16x16 tilemap
dim map(16, 12) as ubyte

' Initialize map with tile numbers
for y = 0 to 11
for x = 0 to 15
' Set tile numbers (0-63)
map(x, y) = (x + y) mod 64
next x
next y

' Draw the map
for y = 0 to 11
for x = 0 to 15
DoTileBank16(x, y, map(x, y), 36)
next x
next y

do
' Game loop
WaitRetrace(1)
loop
</syntaxhighlight>

=== Loading from SD Card ===

<syntaxhighlight lang="basic">
' NextBuild simple load from SD card
#include <nextlib.bas>

border 2: paper 0 : ink 0 : cls

' LoadSD(filename,address,size,offset)
ShowLayer2(0)

do
LoadSD("screen2.scr",16384,6912,0)
border 0
pause 100
loop
</syntaxhighlight>

=== Saving to SD Card ===

<syntaxhighlight lang="basic">
#include <nextlib.bas>

dim n as ubyte

paper 7: ink 0: border 7: cls

print ink 1;"Lets print some text.." : pause 50 : cls

for n = 0 to 22
print "HELLO THERE WORLD ! ! ! ! ! !"
ink rnd*7
next

' SaveSD(filename,address,number of bytes)
' lets save the screen
SaveSD("output.scr",16384,6912)

pause 100 : cls
print ink 1;"Screen saved to SD.."
print ink 1;"Lets load it back.."
pause 100

' LoadSD(filename,address,number of bytes,offset)
LoadSD("output.scr",16384,6912,0)

border 1 : pause 0

do
loop
</syntaxhighlight>

== Layer 2 Image Drawing ==

<syntaxhighlight lang="basic">
'!org=24576
' NextBuild Layer2 Template

#define NEX
#define IM2

#include <nextlib.bas>

asm
' setting registers in an asm block means you can use the global equs for register names
' 28mhz, black transparency,sprites on over border,320x256
nextreg TURBO_CONTROL_NR_07,%11 ' 28 mhz
nextreg GLOBAL_TRANSPARENCY_NR_14,$0 ' black
nextreg SPRITE_CONTROL_NR_15,%00000011 ' %000 S L U, %11 sprites on over border
nextreg LAYER2_CONTROL_NR_70,%00000000 ' 5-4 %01 = 320x256x8bpp
end asm

LoadSDBank("pirate-win.raw",0,0,0,32) ' load in pirate 1
LoadSDBank("pirate-loss.raw",4096,0,0,32) ' load in pirate 2

Cls256(0)

do
DrawImage(0,0,@image_pirate,0) ' frame 0 pirate 1
WaitKey()
DrawImage(0,0,@image_pirate,1) ' frame 1 pirate 2
WaitKey()
loop

image_pirate:
asm
' bank spare
db 32, 64, 64
' offset in bank
dw 2
end asm
</syntaxhighlight>

== File Formats ==

=== Sprite Files (.spr) ===
Binary files containing sprite data. Each 16x16 sprite uses 256 bytes (or 128 bytes for 4-bit sprites).

=== Palette Files (.pal) ===
Color palette data files.

=== Audio Files ===
* .afb: AYFX sound effects bank
* .pt3: ProTracker 3 music files

== Building and Running ==

# Press Ctrl+Shift+B or select "Run Build Task" to compile your project
# If compilation succeeds, CSpect emulator will launch with your program
# Press ESC to exit CSpect (F1 enters the debugger)

== Debugging ==

# Press F1 in CSpect to enter the debugger
# Use the Memory window to inspect memory contents
# Set breakpoints with the BREAK or BBREAK macros in your code

== Additional Resources ==

* Full NextLib command reference: [https://zxbasic.readthedocs.io/en/docs ZX Basic Documentation]
* ZX Spectrum Next Hardware Manual for detailed hardware specifications
* Example programs in the Sources/examples directory

== Common Issues and Solutions ==

* '''Compilation Error''': Check the COMPILE.TXT file for error details
* '''Bank Conflicts''': Ensure you're not using overlapping memory banks
* '''Graphics Issues''': Check palette settings and Layer 2 initialization
* '''Sound Not Working''': Verify IM2 is properly set up and banks are correct

== Credits ==

NextBuild would not exist without the help of many contributors including:
* Jose Rodrigez / Boriel
* Mike Dailly
* D Rimron Soutter
* Robin Van HagenGuest
* Michael Flash Ware
* Kev 9bitColor Brady
* Jim Bagley
* Dufectu
* sol_hsa
* ped7g

Talk:Main Page

2025-04-11T22:51:49Z

Em00k: Created page with "Added the link under the FAQ heading, as it can appear that clicking "FAQ" in the contents can look like the current page is the FAQ."

Added the link under the FAQ heading, as it can appear that clicking "FAQ" in the contents can look like the current page is the FAQ.

Main Page

2025-04-11T22:50:24Z

Em00k: /* FAQ */

== References ==

=== [[FAQ]] ===

[[FAQ|Click here to go to the FAQ page]]

=== System architecture ===
* [[Specifications]]
* [[Extended Z80 instruction set]]
* [[Memory map]] and switching mechanics
* [[Reference machines]] and timing
* [[Boot Sequence]]
* [[Board feature control]] (NextRegs) and port list
* [[Interrupts]]
* [[RPi0 Acceleration]]
* [[DMA|zxnDMA]]
* [[CTC]]
* [[Copper]]
* [[File Formats]]
* [[Z80 programming]]

=== Video ===
* [[Video Modes | Enhanced ULA Modes]]
* [[Tilemap]]
* [[Sprites]]
* [[Layer 2]]
* [[Palettes]]
* [[Blend Modes]]
* [[Refresh Rates]]

=== Audio ===
* [[Turbo Sound Next]]
* [[SpecDrum/DAC]]
* [[Beeper (audio) | Beeper]]

=== Firmware ===
* [https://gitlab.com/thesmog358/tbblue TBBlue Official Distribution git repository]
* [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/tree/master Official Next Core git repository]
* [[NextZXOS]]
* [[ESXDOS]]
* [[NextBASIC]]
* [[System Variables]]
* [[API|esxDOS and NextZXOS APIs]]

=== Electronics ===
* [[Circuit Diagrams]]

=== [[Development Tools]] ===
* [[Emulators]]
* [[Assemblers]]
* [[Compilers]]
* [[Audio_/_Music | Audio/Music]]
* [[Miscellaneous]]

=== Hardware Expansion ===

Your next computer can be expanded internally to add additional functionality.
* [[RTC | RTC - Real Time Clock]]
* [[RPi0_Acceleration| Accelerator - Raspberry Pi Zero]]
* [[ESP8266-01 | ESP8266-01 - Wifi Module]]
* [[Expansion | Expansion Slot]]
* [[GPIO Socket (J15)]]
* [[JTAG Socket]]
* [[2MB RAM Expansion]]
* [[Beeper (hardware) | Beeper]]
* ''[https://www.specnext.com/forum/viewtopic.php?f=6&t=544 Specnext Forums]
: A link to the forums discussing hardware additions

=== Peripherals ===

* [[Mouse]]
* [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt Pinouts (Joystick / VGA / GPIO / Daugherboard / Beeper]

=== Classic Peripheral Information ===

* [[esxDOS together with Interface 1]]

= Community =

* [https://www.specnext.com/forum/ Official forums]
* [https://www.facebook.com/groups/specnext Facebook group]
* [https://discordapp.com/invite/HdRvZVw Discord chat]
* [https://www.specnext.com/ Official site]
* [https://wiki.specnext.dev/ZX_Next_Clones Running the Next core on ZX Next clones]

= Sources =
* [[Bibliography]]

= Wiki "to do" list =
* [[Wiki TODO list]] (can be used also as warning which pages may contain outdated information)

FAQ

2025-04-11T22:43:43Z

Em00k: /* My internal keyboard is not responding – help! */

== I am using HDMI and I get no picture ==
When the Next boots hold down D for DIGITAL (HDMI) – Mode 7 50hz / 60hz can be selected. N selects the next frequency, ENTER selects it and saves. ONLY PRESS ENTER if you actually see a screen like the one below. N is NOT necessary as the testscreen will automatically go to the next mode albeit slower.
[[File:Figure02-TestScreenMode7.png|thumb|ZX Spectrum Next Test Screen]]

You will also get an audible intermittent tone so you know your audio is working. It's possible your display can lock onto both modes but only one being able to lock onto the audio. Choose the one with the tone before pressing ENTER. Extract the files and copy over the BIN / SYS/ TMP folders to the root of your SD.

== How to use esxDOS with 48K mode ==
[[File:2023-12-17 21 01 56-Window.png|thumb|esxDOS files]]
Your ZX Next can simulate the divMMC hardware for other machines. You can use esxDOS with 128/48K machines. You can download the latest esxDOS zip file here https://esxdos.org/index.html Download the zip and copy over the following folders BIN/SYS/TMP.

You will need to place the ESXMMC.BIN in to /machines/next/roms

Boot up your Next and press SPACE to open the configuration menu. Use the arrow keys to select 48K Mode, SPACE again and ensure DIVmmc ROM = YES. Exit and save this configuration. When your Next boots it should show the esxDOS logo just before the (c)1982 Sinclair Research Ltd message.

[[ESXDOS|Further information can be found here]]

[[File:Pre boot machine select menu.png|thumb]]
[[File:2023-12-17 21 21 11-OBS 30.0.0 - Profile Untitled - Scenes Untitled.png|thumb]]

== I am using VGA and I get no picture ==
When the Next boots hold down V for VGA – Mode 0-6 50hz / 60hz can be selected. VGA0 is the
preferred mode as this has accurate timings. 1 – 6 are also accurate timings but increase slightly
in speed. N works as above but there are 12 possible configurations you can choose from. You'll start at VGA0@50Hz, next one will be the same at 60Hz and so forth. ENTER again selects and saves the changes. Audio is also being produced during the VGA Test Screen phase, however you will need powered speakers (or earphones) plugged in the audio out connector at the back of your Next.

== I'm using an HDMI display and a game's graphics appear garbled ==
Some games (specifically ones with multicolour or border effects - eg. Nirvana/Bifrost engine games, certain demos particularly ex-Soviet demoscene ones) require precise timings as with a regular Spectrum. Due to the nature of HDMI displays and the lack of internal buffering on the Spectrum Next display hardware currently these will not work properly and require a VGA or RGB display.
This is expected to be fixed in a future edition of the core/distribution but until then, there are a few alternative solutions:
a. An extra Spectrum core that implements precise HDMI timings by removing some of the Next's extra features.
b. Use of OSSC hardware which takes the Next's RGB/VGA display and converts it to HDMI independently
c. Use of the ZXHD or TkPie hardware expansions (only for standard Spectrum modes at 3.5MHz clock)
Next specific programs do not have this issue as they're made taking the current HDMI timing differences into account and will continue to work in the future when the most appropriate HDMI solution is implemented.

== I am updating to the latest distro from GitLab or the N-Go website and my ps/2 keyboard doesn't work ==
To use a ps/2 keyboard you need to first choose whether you have a mouse or keyboard plugged into your ps/2 port. Unfortunately you can't get to the screen where you can make this choice ''until'' you have chosen your video mode on the testcard screen... which ''needs'' the keyboard to be already working!

Download this minimal config.ini file [https://dl.dropbox.com/s/5na7sd21328jnz5/CONFIG.INI] and copy it to the '''/Machines/Next''' folder on your SD card, then try again.

When updating your distro from the official [[https://www.specnext.com/latestdistro/ Latest Distro]] page, or when using the internal keyboard on your official kickstarter 1 or 2 Next, this problem will not occur.

== My monitor shows wrong image with Soviet timings(Pentagon) ==
Pentagon has a non-standard screen refresh rate of 48.828Hz, some monitors do not support it. In some cases, can help manual picture settings in menu of your monitor.
Another solution to the issue is to buy a monitor that is compatible with Pentagon timings. User-generated list of compatible monitors located here: http://www.nedopc.com/zxevo/zxevo_supported_monitors.pdf
As a rule, monitors from this list are available on the secondary market at a low cost. Before purchasing desirable testing monitor with Pentagon mode.

== HELP! My <insert game name here> doesn't work while it works on my <insert older Spectrum model here> ==
This is most likely due to a specific incompatibility of said program with the Next's extra hardware. The NextZXOS loader module, provides a lot of options for loading software catering to each model's idiosyncracies but also gives you the option to disable almost all Next extra hardware in order to make it work. If, after trying everything, the software doesn't work, you need to inform the team using the official gitlab repo "Issues" (registration is required) and provide a link to a copy of your program. The team will look at the specific issue and respond/fix the issue as soon as possible.

== What classic files can I load on my Next? ==
The Next supports NEXs, TAPs (preferred for classic software), SNAs, DSKs, Z80s, SNXs which can be loaded from the browser
menu by selecting them with the cursor keys and ENTER (or a joystick and Fire) -OR- by using the SPECTRUM command. (See Chapter 20 in the manual for details).
Place the files on your SD card and pick from the Browser.

== How to load from a software cassette tape ==
For a successful load a clear signal from the player has to arrive on the "ring" part of the plug which you insert in the EAR/MIC socket of your Next, as in the picture "Next's EAR/MIC socket wiring".
[[File:Ear-mic-socket-1.png|thumb|Next's EAR/MIC socket wiring]]
The plug inserted into the Next is referred to in many descriptions as a "3.5mm stereo plug". Even if the Next always uses a single channel to load, the plug on its side has to be the same as those used for stereo (two channel) equipment, because, as stated, it then receives the signal over the "ring", which doesn't exist on "mono" plugs. That's also why the cables delivered with the Spectrum 128 and earlier models won't work: their both sides lack the ring on their plugs.

So the cable on the Next's side needs a 3.5mm plug commonly described as a "stereo" plug. The other side will depend on the output socket on your cassette player.

[[File:Spectrum-plus-3-tape-lead.jpg|thumb|ZX Spectrum Next/+3 Tape Lead]]

To load from a player with a ''mono earphone'' socket: you can try to use, if you have it, a cable made for Spectrum +3 or later (see the picture: "ZX Spectrum Next/+3 Tape Lead"), or, you can try to obtain an [https://store.activeconsult.co.uk/shop?olsPage=products%2Fear-mic-cable&page=2 "Ear/Mic Cable"], or, as a possible substitution, a TRS stereo cable and a fitting stereo to mono adapter.

All other scenarios need different solutions. Often, if the player has a 3.5mm ''stereo'' socket and the signal on its right channel sounds good, then a plain TRS cable with 3.5mm plugs on both sides could work (in TRS, the T stands for the "tip" and the R for the "ring" of the plug). Otherwise, including in the case where you want to connect a mono socket from the player and you can't obtain or use the linked "Ear/Mic Cable", the rule is still: the Next needs a clear and strong signal on its "ring" connection. The standard for analog stereo and AV cables or adapters which split the "stereo" side to separate channels on another side is to call the separated audio channels the left and the right channel and to assign white and red color to them, respectively. On those, the ''Red'' one is the one connected to the ''Ring'' needed by ZX Spectrum Next when loading. (Note 1: Memory aid: R-R-R, red-ring-right) (Note 2: Typically, the splitters to mono signals will have bigger sockets or plugs, called RCA: unless sockets on the player match, one splitter won't be the enough to construct the whole solution, but two can be combined, the second used to lead two, still separate, signals to a single multi-channel plug. A splitter allows to try which of the two channels from a stereo player has a better signal). (Note 3: when orienting the common splitters, the color mark from the historic +3 cable picture should be ignored: even if that cable is also a splitter, differently from the "stereo" convention, on it, the black side is the "right" one).

NextZXOS provides a Tape Tester in the main menu of NextZXOS – Select More and Tape Tester. It can help once you already have a signal but need to find the best volume or, in some cases, adjust the azimuth. Once you are ready to load a real tape choose the Tape Loader and press PLAY on your player.

== How can I load TZX files? ==
TZX files can be loaded if you have a pi0 or an external TZX player. If you have a pi0 please see
below for more information. Before asking for help please have this information ready 

== My LED does not go out when I unplug the power! ==

[[File:Next HDMI PSU.jpg|thumb|Remove ALL cables]]
Some TVs will back-power the Next through the HDMI cable, so it’s important to '''REMOVE ALL CABLES''' after a firmware
update and to turn off completely. If your TV/Display has multiple inputs try using one of the other ones as usually NOT ALL HDMI ports exhibit this behaviour.

The back-power situation also happened in one case with I/O serial cable used at joystick port, general rule seems to be "if it has own power, and is connected to Next, it may back-power it" - in case of problems to power-cycle the Next properly, unplug all such cables/peripherals first and try again.

== How do I update my Next? ==
Latest stable distro is [https://www.specnext.com/latestdistro/ here]. To update your Next, extract the contents of the distro to your SD card. Power down the Next,
Press and hold U and power on until you see the Updater screen and follow the instructions. As
above if you are using HDMI you need to remove all cables when instructed to power off your
Next.

You can also read [https://www.specnext.com/forum/viewtopic.php?p=13644 this forum post] by Allen with greater detail about the update process.

You may occasionally be directed to download the latest versions from gitlab [https://gitlab.com/thesmog358/tbblue here]. Sometimes this is desirable if you're being asked to test a specific fix or recent hardware features.

== My SD card is not recognized by my Next during boot ==
The Next supports FAT32 (including long filenames), FAT16 and FAT12. It does '''not''' support exFAT, NTFS, AFS or ext formats. Some disk formatters, such as the Windows GUI formatter and the SD Association Formatter, force exFAT for SD cards 32GB or larger, and will '''not''' let you format with FAT32. On Windows, format with <code>format x: /FS:FAT32</code> using the command line (where x: is the drive letter your card is mounted as).

== How do I update the Pi in my Next (NextPi)? ==
NextPi that came with KS1 and requires a 1GB SD card can be downloaded [https://zx.xalior.com/NextPi/ here], and you can use [https://www.balena.io/etcher/ Etcher]. For NextPi2 (recommended) you will require a 16GB SD card and can download from [https://zx.xalior.com/NextPi2 here.]

== I have a pi0 but cannot get TZXs to load ==
You will require a new updated '''dot/pisend''' and '''nextzxos/tzxload.bas''' from the
[https://gitlab.com/thesmog358/tbblue git repository]. These need to be placed in the correct folders on your SD
card. These files have updated after the distro was released. 
You can check if the pi0 is correctly responding by going into Command Line and running “.term”
You should see Terminex, press SYM+SHIFT+B to switch to 115,200 baud and press Enter. If you
see the words “SUP>” then your pi0 is ready. You can quit Terminex by pressing SYM+SHIFT+Q

To load a TZX, place some TZX files on your SD card and you should be able to select the files
from the Browser and the Next should do the rest. If you come across a game that doesn’t work
please let us know.

I have problems loading TZXs: 
 
Are you on the latest core / NextZXOS? 
Have you updated to the latest git distro? [https://gitlab.com/thesmog358/tbblue/-/archive/master/tbblue-master.zip git repository] 
What video mode are you using? (VGA0/HDMI etc) 
What game didn't work? (You need to supply the exact name) 
Where did the loading fail? Did the game load fine but crash etc? 
Have you left something plugged into the EAR port? 

== How do I sort the contents of my SD card? ==
On NextZXOS 2.07 and above, the browser can sort files dynamically. Press O to toggle between ordering by date, size and none. Press + (SYM+K) to toggle between ascending and descending order.

For esxDOS or older versions of NextZXOS, you will need to use a tool on a PC such as [http://www.anerty.net/software/file/DriveSort/?lang=en DriveSort] (Windows) or [https://fatsort.sourceforge.io/ FatSort] (cross OS compatible) to physically reorder the files in the SD card's directory database.

== Where do I buy RTC / Mouse / Memory / Wifi / Pi0 / Inline Power Switch… ==
ActiveConsult sell most of these products and can be found [https://store.activeconsult.co.uk/shop?olsPage=products&page=1 here].
SCART cables can be purchased [https://coolnovelties.co.uk/coolnovelties/sinclair-zx-spectrum/312-zx-spectrum-next-analog-rgb-scart-cable-0705693507088.html here], also here: [https://www.retrocomputershack.com/] NOTE that you will need to boot your ZX Spectrum Next and press the R key to set up the SCART output.

== What controller / joystick / gamepad can I use? ==
[[File:Atari-2600-Paddles.jpg|thumb|Atari 2600 Paddles]]The Next supports any “Atari” standard joystick or gamepad, along with Master System and MegaDrive pads. A good option is the [[M30 8BitDo wireless MegaDrive pad]].
You '''CANNOT''' use the '''Sinclair Branded SJS-1''' joysticks sold for +2/2A/3 ZX Spectrums as they require a special adapter.
If your joystick has both black and grey plugs, '''DO NOT''' plug in the grey plug, as that only works on +2/2A/3 ZX Spectrums and will damage your Next.

The Next also supports [https://www.atariage.com/controller_page.php?ControllerID=3&SystemID=2600 Atari 2600 driving controllers]. These are digital quadrature rotary encoder devices, identifiable by the word "driving" and picture of a racing car. [https://www.atariage.com/controller_page.php?SystemID=2600&ControllerID=2 Atari 2600 paddles] (identifiable by the word "paddle" and picture of tennis rackets) contain analogue potentiometers, which are '''NOT''' physically compatible and could damage your Next.

== How do I configure the joystick ports to be Kempston / Sinclair / Megadrive / Cursor? ==

Your Next lets you configure how each joystick port behaves. By default the Left port will be configured to Kempston1 and Right will be Sinclair1. If you wish to change this configuration press the NMI button, Choose "Settings", then "Joysticks". You can now select JoyL for Left or JoyR for right and cycle through the options : 
 
Kempston1 
Kempston2 
Cursor 
Sinclair1 
Sinclair2 
MD 1 (Megadrive 3/6 buttons) 
MD 2 (Megadrive 3/6 buttons) 
 
You cannot set both ports to the same configuration. This will only set the choice until a cold reboot (complete power off). You can set these options to be permanent by powering off your Next, on the Sinclair ZX Next boot screen hold down SPACE, then press 'E' - Change the options for Left Joy and Right Joy with SPACE. Once you have chosen your preferred joystick configuration press ENTER twice. Your Next will now reboot and once back into NextZXOS your settings will now be applied. 

== My ZX ProPad Button 2 Doesn't Work ==
The Next only supports two directly wired fire buttons. On the ZX ProPad these are buttons 1 and 3. Additional buttons are supported for Sega Megadrive pads and sticks only. Both 3 and 6 button Sega pads are compatible. Up, down, left, right, A, B, C, X, Y, Z, Start and Mode are all readable.

The limitation of two directly wired fire buttons on non-Sega pads and sticks is baked into the Next hardware, unfortunately. So it cannot be enhanced in a future core update. All Next boards have a physical multiplex chip which hardwires six pins as input only (for direction and two fire buttons), one pin as output only (for Sega select), one pin as 5V, and one pin as ground.
== How do I change the CPU speed/ Scanlines etc? ==
The following keys combinations can be used to : 
NMI + 1 Hard reset 
NMI + 2 toggle scan doubler 
NMI + 3 toggle 50 / 60 Hz 
NMI + 4 Soft reset 
NMI + 7 Toggle scan lines (25/50/75%) 
NMI + 8 Toggle CPU speed (3.5/7/14/28) 
NMI + 9 NMI menu 

== Where can I download games / roms ? ==
[https://spectrumcomputing.co.uk/ Spectrum Computing] and [https://www.worldofspectrum.org/ World of Spectrum] are good places to start. If your Next has wifi, [[https://github.com/em00k/next-zxdb-downloader zxdb-dl]] can also search and download directly on your Next. zxdb-dl is also on your SD card as part of the latest distro.

== My internal keyboard is not responding – help!==
First turn off the Next completely and remove all cables and try again. Failing that a keyboard
cable may have become loose. You can watch a video on how to open your Next here: 
https://www.youtube.com/watch?v=iLDz4AjL3rA also see [[NexTest|NexTest diagnostic tool]]

== My ps/2 keyboard is not responding – help!==
Edit your '''c:/machines/next/config.ini''' file so that '''ps2=0''', or use a [https://store.activeconsult.co.uk/shop?olsPage=products%2Fps2-keyboard-mouse-splitter ps/2 splitter].

== How do I install pi0 / Wifi / RTC / Memory? ==
As above a guide on how to open your Next can be viewed. Also read the appropriate Chapter in the manual.
[https://www.youtube.com/watch?v=iLDz4AjL3rA here].

== How do I connect to Wifi? ==
You can connect to a 2.4Ghz wifi network, make sure your password does not contain spaces. You can use the application wifi2.bas from /apps/wifi/setup - when you load wifi2.bas and type RUN to start

You can confirm your IP address by going in to command line and typing .uart then the following:

AT+CIFSR

This should return your IP. If you are still having issues confirm the network is 2.4Ghz and you are not too far away from an access point.

See if other internet apps work, try ZXDB-DL from /apps/wifi/zxdb-dl and launch zxdb-loader.bas. When the program launches enter a game search term and press return. If you see results wifi is working.

== How can I get the expansion bus working with external hardware? ==
By default, the Next disables the expansion bus, as external hardware can conflict and is unlikely to run at CPU speeds faster than 3.5MHz. The bus can be enabled and and individual conflicting internal hardware disabled through Next registers 128 and 130..137 (manual pages 270..271). [https://www.specnext.com/forum/viewtopic.php?f=6&t=1482&p=9701&hilit=RAM+music+machine+expansion+bus#p9701 Here] is a detailed example of getting the RAM Music Machine working, and [https://www.youtube.com/watch?v=EU9NTQqQ1fg here] is a video demonstrating unsing Interface 1/microdrives.

== Can I use Amstrad/Sinclair SJS-1 joysticks with the Next? ==

'''NO!''' [https://rk.nvg.ntnu.no/sinclair/computers/peripherals/sjs1.htm SJS-1 joysticks] have fundamentally incompatible wiring compared with the standard Atari-wired joysticks the Next uses. Using them on the Next will short the 5V line to ground, potentially damaging your Next. Bin them, sell them, or keep them for your original +2, +2A or +3, where they will work fine but still be quite rubbish.

== Why don't my VGA/joystick sockets have hex nuts to screw the cable in? ==
VGA sockets with hex nuts are typically bolted to a metal chassis. On the Next there is no chassis to screw onto, so you would just be screwing into the connector which is a VERY bad idea. The Next sockets are only fixed tight with small solder pads.
VGA cables are heavy and will put a lot of leverage on the VGA PCB pins, and likely to fracture the PCB or pins on the VGA socket. An unscrewed cable will still stay firmly in the socket during normal use, but will safely unplug if you yank the cable or leverage the plug.

== I thought I had the latest version of the distro? ==
Go by the version numbers of the firmware, core and NextZXOS when deciding if you have the latest version. Ignore the post date on the [https://www.specnext.com/latestdistro/ latest distro] page. Wordpress post dates don't automatically update when existing posts are edited.

== Why doesn't the manual have a table of contents / index ==
Short answer: It didn't fit in the box as the boxes were made way before the manual was completed.
Long answer: TL;DR :)

== Where can I download a copy of the manual with a ToC and index? ==
Right here : https://www.specnext.com/zx-spectrum-next-user-manual-first-edition/

Myopian's [https://www.cs.hmc.edu/~oneill/specnext/manual-fixed.pdf fixed version] displays correctly in Safari, and can be read directly in browsers.

== Further Spectrum Next Video Guides ==
https://www.youtube.com/playlist?list=PL2lCM2mJCG_AonDyHJfqjxFR5VoqBWqoh

== Which Raspberry Pi Model Can I use for the Next Accelerator? ==
Pi Zero 1.3 has fairly major design changes from 1.2, but as long as you’re using official NextPi images and using it as advised you should see no issues using the original 1.2 Pi Zero (the one without camera connectors). The Pi Zero 1.3 will also work just fine, and doesn’t use the camera connector even if found.

The Pi Zero W (all of 1.x ones) are very similar to the 1.3. NextPi can use it, and will disable the wireless.

It’s worth knowing that, ''in theory,'' someone could develop a plugin for NextPi that only works for the the non wireless version, but the only people to do that so far are the Next Team, to prove it was possible.

The Pi Zero 2 series is not supported, has never been supported, won’t work properly, and no support is offered or given into getting it to work properly. Neither are any other non-Zero Pi models, or clones such as Banana Pi.

Other, non-official, "NextPi-compatible" distributions are starting to come available, from 3rd party users and - so far - are NOT fully nextpi compatible, at all.

== Essential Lesser-Known Technical Docs ==
* The master [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/nextreg.txt nextreg] and [https://gitlab.com/SpectrumNext/ZX_Spectrum_Next_FPGA/-/blob/master/cores/zxnext/ports.txt port] lists are kept up to date, and fully describe the Next hardware for developers.
* The [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/extra-hw/pinouts/pinouts.txt pinouts] list has detailed information on connectors.
* The [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/nextzxos-changelog.txt NextZXOS change log] details what was new and fixed in each version of NextZXOS/NextBASIC.
* The four [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos NextZXOS PDFs] have detailed information on the NextZXOS and esxDOS APIs, NextBASIC sysvars, and NextBASIC syntax.
* varmfskii's [https://raw.githubusercontent.com/varmfskii/zxnext_code/master/zx_next_notes/zxnext_notes.pdf ZX Spectrum Next Programming Notes] are an attempt to consolidate the Next programming interface into a single location.
* Myopian's [https://docs.google.com/spreadsheets/d/1dB8fKIfByGJTts409Ud8ly450a6SLPnLZc-nCBghBl8 API spreadsheet] summarises NextZXOS/IDEDOS entry points along with calling conditions.
* Myopian's [https://www.cs.hmc.edu/~oneill/specnext/dot-cmds.html dot command summary] collects together help and readme text for NextZXOS dot commands in one handy place.
* Tomaz's [https://github.com/tomaz/zx-next-dev-guide/releases/latest ZX Spectrum Next Assembly Developer Guide] is almost like "User manual" for Assembly developers.
* Luzie/Rat Mal's [https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/edit?usp=sharing_eil&ts=599361c7 Almost (In-) Complete List of esxDOS DOT-Commands] attempts to list dot commands for several systems, including the Next. Some of the non-Next-specific commands may work on the Next, and some may only work on other FPGA/divMMC systems.

NextTest

2025-04-11T22:42:40Z

Em00k: Em00k moved page NextTest to NexTest: Spelling

#REDIRECT [[NexTest]]

NexTest

2025-04-11T22:42:40Z

Em00k: Em00k moved page NextTest to NexTest: Spelling

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

[[File:Nextest Joystick Detail.png|left|Joystick detail]]

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-11T22:40:23Z

Em00k: /* Kempston Joystick */

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

[[File:Nextest Joystick Detail.png|left|Joystick detail]]

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-11T22:39:42Z

Em00k: /* Kempston Joystick */

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

[[File:Nextest Joystick Detail.png|left|Joystick detail]]

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-11T22:39:14Z

Em00k: /* Kempston Joystick */

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

[[File:Nextest Joystick Detail.png|frameless|left|Joystick detail]]

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

File:Nextest Joystick Detail.png

2025-04-11T22:38:37Z

Em00k:

Shows the Joystick detail

NexTest

2025-04-11T22:34:50Z

Em00k:

[[File:Nextest-screenshot.png|right|600px]]

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-11T22:33:54Z

Em00k: /* NEXTEST v2.0A User Guide */

= NEXTEST v2.0A User Guide =

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor

NexTest

2025-04-11T22:33:00Z

Em00k: /* Welcome */

= NEXTEST v2.0A User Guide =

[[File:Nextest-screenshot.png|center|600px]]

== Welcome ==

'''NEXTEST''' is a test application for the ZX Spectrum Next. It automatically checks the SRAM and SD card transfer bus, while allowing the user to verify input devices manually. It is included on the official distro in C:/EXTRAS/NEXTEST/NEXTEST.NEX

The test duration is left to the user's discretion and may range from minutes to several hours of soak testing.

== Requirements ==

* Runs under '''NextZXOS v2.1''' or later.
* Requires '''core v3.00.00''' or later.
* Compatible with all CPU speeds and video mode configurations.
* Detects systems with 1MB or 2MB RAM.
* The SD card used to launch `NEXTEST.NEX` must remain inserted during testing.
* A mouse is recommended but not required.

== Configuration ==

* Default CPU speed is set to '''28MHz''' at startup.
* Speed drops to '''3.5MHz''' if the expansion bus is enabled.
* Respects user configuration for machine timing, video mode, and refresh rate.
* '''NMI/Multiface''' and turbo shortcut key are disabled while running.
* Both joystick ports are set to '''Mega Drive mode''' to support multi-button gamepads.
* '''Power-off or reset''' is required to exit.
* SD card is treated as read-only – no file writes are performed.

== Startup ==

The application performs several quick checks during startup:

* Data and address bus verification.
* CRC check on the application binary.
* Checks for:
* Operating system version
* Core version
* SD card
* Video mode
* Machine identity

The application relocates into the '''16K bank shared with the ULA'''. This memory is shadowed in FPGA BRAM for additional protection against SRAM issues.

'''Note:''' The CRC status should read '''PASS'''. A failed CRC indicates a corrupt application and unreliable results.

== Display ==

* Uses a '''640×256 screen''' layout.
* System information is displayed at the top in a large font.
* Test results and status appear below in a smaller font.
* '''Green text = pass'''; '''Red text = fail'''.
* A multi-colour ZX Spectrum Next graphic is displayed centrally.
* On fatal errors, a black "stop screen" with a bold white error message is shown.
* Reset or power-off is required to exit a fatal error screen.

== Navigation ==

* A mouse is required to change:
* CPU turbo speed
* Refresh rate
* Machine timing

* Tooltips are displayed in the top-left when hovering over active areas.
* Left and right mouse buttons cycle through configurable parameters.
* Tooltip text shows warning messages if a mode is locked.
* The 3.5MHz speed is displayed as '''3MHZ'''.

== Automatic Tests ==

Background tasks run continuously, regardless of user input:

# SRAM bit inversion write/verify
# DMA write/verify
# SD card read/verify
# Real-time clock (RTC) poll using the NextZXOS API

* Background tests loop indefinitely.
* Completion time varies with CPU speed.
* Memory bank ID, SD card block, and RTC status are updated in real-time.
* Memory errors at or above bank 95 are shown as '''95''' in the bottom-right.
* SD card CRC checks are disabled at 3.5MHz.

== Manual Tests ==

The following inputs are monitored and displayed in real-time:

* Keyboard
* Mouse
* Joystick
* Board buttons

=== Kempston Joystick ===

* Inputs shown as:
* '1' when pressed
* Initial letter of the direction/button when released
* Letters used:
* '''SACBUDLR''' = Start, A, C, B, Up, Down, Left, Right

=== Kempston Mouse ===

* X range: 0–319
* Y range: 0–255
* Scroll wheel: hex 0–F
* Buttons:
* '1' when pressed
* Initial letter when released: '''LMR''' = Left, Middle, Right

'''Note:''' Mouse pointer may be invisible at display edges.

=== Keyboard ===

* Keys flash until pressed
* I/O port number for each group is shown
* All keys (including extended and shifted combos) are translated and shown on the graphic
* Pressed keys turn red; a stuck key stays red

=== Audio ===

* 3.5mm jack outputs a looping audio track streamed from the SD card
* HDMI audio is supported (if display device allows)
* '''Glitches are normal''' when switching refresh rate or machine timing

== Fatal Errors ==

Each of these messages appears as a stop screen. A system reset or power-off is required.

<pre>
CORE V.3.00.00 OR ABOVE REQUIRED
NEXTZXOS 2.01 OR ABOVE REQUIRED
ESXDOS API ERROR
NEX LOAD ERROR
FILE ERROR
FILE FRAGMENTATION ERROR
DISK FILEMAP ERROR
SD CARD STREAM ERROR
SD CARD NOT READY
DATA BUS ERROR
ADDRESS BUS ERROR
</pre>

== Credits ==

* Design and development: '''Kev Brady'''
* Music: '''"Humanoids"''' written and produced by Kev Brady
(c)2023 9bitcolor