Difference between revisions of "NextBuild:Main Page"

From SpecNext official Wiki
Jump to: navigation, search
Line 1: Line 1:
−
'''So what is Nextbuild?'''
+
= NextBuild v8 =
  
−
It's an environment for developing in BASIC for the Spectrum Next, which combined with MS VSCode (other editors are available!), ZXBasic compiler, and an emulator on a Windows, linux or apple PC gives pretty decent performance and Rapid development. It's a bunch of glue, plus a fairly extensive library, along with some examples,  which allow access to a lot of the hardware banging functions of the Next with ease, at speeds you couldn't dream of in NextBasic. (Not NextBasic's fault of course - it's interpreted so is always going to have an overhead which NextBuild/ZX basic doesnt have.)
+
== Introduction ==
  
−
Contributions and ideas for Nextbuild are actively encouraged and there is a Boriel section on Discord which is well used by users of Nextbuild.
+
=== NOTE : This documentation is still in progress ===
  
−
What are you waiting for? click the link below :)
+
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.
  
−
[http://zxbasic.uk/nextbuild/ About NextBuild]
+
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

Revision as of 01:35, 12 April 2025

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 [1].

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

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

Project Structure

/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.)

Creating Your First Project

  1. Create a new .bas file in the Sources directory
  2. Add the following template:
'!org=32768
'!heap=2048
'!opt=4

#include <nextlib.bas>

' Your code here

do
    ' Main loop
loop
  1. 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:

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

' 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$)

Layer 2 Graphics

' 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)

Tile Operations

' 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)

Pixel Operations

' 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)

Palette Management

' Upload a palette
PalUpload(address, colors_count, offset, bank)

Sprite Operations

' 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)

Memory Management

' Get/set MMU banks
MMU8(slot, bank)
MMU16(bank)
GetMMU(slot)
GetReg(register)

Timing and Synchronization

' Wait for vertical retrace
WaitRetrace(frames)
WaitRetrace2(line_number)
' Wait for key press
WaitKey()

Music and Sound Effects

' 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)

Memory Management

MMU Slots

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

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

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)

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: 

'!org=32768     ' Program start address
'!bmp=intro.bmp ' Loading screen

Extending With Interrupt Mode 2

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

#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

Examples

Drawing a Sprite

'!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

Tile-Based Game Screen

'!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

Loading from SD Card

' 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

Saving to SD Card

#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

Layer 2 Image Drawing

'!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

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

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

Debugging

  1. Press F1 in CSpect to enter the debugger
  2. Use the Memory window to inspect memory contents
  3. Set breakpoints with the BREAK or BBREAK macros in your code

Additional Resources

  • Full NextLib command reference: 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
Retrieved from ‘http://wiki.specnext.dev/index.php?title=NextBuild:Main_Page&oldid=13535’