Boriel Basic Forum - Portal

GuSprites

Sat, 13 Jun 2026 08:36:59 +0000

After a little while away from Boriel and am returning to it. I have been looking at GuSprites, but the documentation is limited. Is there any tutorials or documentation that would help a beginner?

New video Couse / Nuevo curso en vídeo

Wed, 29 Apr 2026 22:02:22 +0000

English
I’m creating a video course on Boriel Basic.
You can find it at: https://youtu.be/nBo3eu4XNFY?si=uo7Nz9DhEAToEdNE

-------------------------------------------------------------------
Español
Estoy creando un curso de Boriel Basic en vídeo.
Lo tenéis disponible en: https://youtu.be/8AkYffB--bk?si=eL9yz9oPLpi6y0wE

location of heap management code...

Tue, 24 Feb 2026 13:17:50 +0000

I'd like to use strings and arrays in my paged code, but I seem to have reached a blockage whereby, even though my paged-code looks like:

Code:
#PRAGMA push(case_insensitive)
#PRAGMA case_insensitive = True
#define STANDALONE  ' remove ROM initialization and SysVars...

Asm
    org $6000
    di
End Asm
s_stage_init()
Asm
    ret
End Asm


#include "constants.bas"
#include "globals.bas"
#include "stage-include.bas"


Sub s_init_keyboard_table_ZX_keys()
    ' effect: populates the lookup table for the 40-key spectrum matrix
    ' row 0: port $FEFE
    gub_zxkeys(0)  = 0   ' caps shift
'...
    gub_zxkeys(55) = 127 ' delete (standard)
End Sub


Sub s_init_keyboard_table_ZX_symkeys()
    ' row 0: z, x, c, v
    gub_zxsymkeys(1)  = 58  ' :
'...
    gub_zxsymkeys(55) = 127 ' delete (standard)
End Sub


Sub s_init_title_screen()
    ' footer prompt
    s_print_string_at( 28, 21, "Press any key to begin..."  , UB_BRIGHT_YELLOW )

    ' wait for player input
    s_get_key()
    ' check if the one-hour timeout occurred
    If guw_key_code = 0 Then gub_core_end = true
End Sub


Sub s_stage_init()
    s_init_keyboard_table_ZX_keys()
    s_init_keyboard_table_ZX_symkeys()

    s_init_title_screen()
End Sub

and when I compile with :

Code:
python $Compiler "$($Name).bas" -f bin -o "$($Name).bin" --org 24576 -W150 --headerless --explicit --strict --zxnext -i --arch zxnext --opt-strategy size --heap-address 32000 --heap-size 767 -M "$($Name).map"

then I still seem to end up with some kind of header code that makes a call to $46A4...

Code:
>6001  CALL 46A4        PC  6001
 6004  NOP              SP  FFFA
 6005  NOP              AF  FFFF'3C40
 6006  NOP              SZ5H3PNC
 6007  NOP              HL  0001'3C44
 6008  NOP              DE  0000'FFFF
 6009  NOP              BC  0000'5393
 600A  LD BC, 6013      IX  FFF1
 600D  EX AF, AF'       IY  EFF3
 600E  LD B, A          IR  001B
 600F  NOP              IM1 IFF--
 6010  NOP              (HL) F3 00
 6011  NOP              (DE) 00 F3
                        (BC) 00 F3

(SP) 0C3C 010B 0000 F300 C300 0

which I think must be some kind of heap management setup...

...so please may I ask...

Is there a compiler switch or directive whereby I can get the heap management code tacked on just after my code ends, so that I can have private heap management per 8KB segment of paged code ?

Thank you.

non-paged supervisor code calling paged application code

Sun, 15 Feb 2026 15:01:23 +0000

Firstly, a proper thankyou to Boriel for the compiler. And secondly, also a proper thankyou to Duefectu for the beginner's guide book (I bought a hard copy), which I have read cover to cover (but I did skip the sound/audio sections ). And I bought a hard copy of Simon G's NextTech book too, again I have read it cover to cover (but skipped the sound/audio parts).

Using Boriel ZXBasic and as little Z80 machine code as I can get away with (until I need to performance tune)... my project is that I am trying to write a quasi "character cell" based application, like being on an old VT100, whereby the application uses all 64KB of the Z80 for itself, and thus no ZX Spectrum ROM, and which internally leverages a poor man's virtual memory framework, whereby I have a supervisor layer of non-paged code running in MMU0/1, which boots from $0000 and jumps over IM1 at $0038 to begin my main code properly at say $0050 where the application begins properly... and so I have my core non-paged system variables mapped in MMU2 and then I have my paged code to run from MMU3 - and then various different aspects of paged application data paging in and out MMU4/5/6, with finally MMU7 again being static non-paged to host the 5KB of screen tile map for an 80x32 screen, with the final 3KB of MMU7 being available for the stack pointer from $FFFE downwards.
phew...
I know my code will never work first time, I get that... but I feel fairly sure that I have the basic (excuse the pun) initial structure of what I want to achieve, with all of my system variables (so far identified) defined at static addresses in MMU2, and my main supervisor MMU paging and also my screen updating routines and keyboard reading routines written (to be permanently resident in MMU0/1) and the first of my paged blocks of code to run from MMU3, and I have gotten the source code clean enough pass through zxbc without the compiler spitting any hard errors... (just lots and lots of warnings)... but I've now hit a roadblock...

I get how I can have many separate pages of 8KB deposited across the ZX Next vast 200+ pages of 8KB across 1.75 MB of RAM, and I get how I can have my code paged in at MMU3 for my application to execute from $6000, and I can get my non-paged supervisor layer code to make calls such as uw_dummy = USR $6000 to call my paged code in MMU3, and thus wait for a return... but what I don't understand is how I can have many different paged code blocks where each is aware of *ALL* of the available core supervisor routines and their parameter structures and thus able to makes calls back in to the supervisor to run any of the many core system routines...

i.e. how can I make zxbc firstly compile the application core without dropping routines that zxbc thinks are unused, and yet also somehow get the compilations of many different "paged" application code to be aware of the core supervisor routines and their parameters and any return value data types (of functions).

e.g. I get this from my compilation of my "core.bas":
core.bas:115: warning: [W170] Function 's_crash' is never called and has been ignored
core.bas:154: warning: [W170] Function 's_fc_ram_copy' is never called and has been ignored
core.bas:165: warning: [W170] Function 's_clear_screen' is never called and has been ignored
core.bas:126: warning: [W170] Function 's_print_char_at' is never called and has been ignored
core.bas:143: warning: [W170] Function 's_print_string_at' is never called and has been ignored
core.bas:217: warning: [W170] Function 's_display_monitor' is never called and has been ignored
core.bas:283: warning: [W170] Function 'fub_key_get_minutes' is never called and has been ignored

...and I get this for my first stage of my application:
stage-include.bas:37: warning: [W170] Function 's_next_reg' is never called and has been ignored
stage-include.bas:38: warning: [W170] Function 's_return_to_zxos' is never called and has been ignored
stage-include.bas:39: warning: [W170] Function 's_crash' is never called and has been ignored
stage-include.bas:40: warning: [W170] Function 's_fc_ram_copy' is never called and has been ignored
stage-include.bas:42: warning: [W170] Function 's_clear_screen' is never called and has been ignored
stage-include.bas:43: warning: [W170] Function 's_print_char_at' is never called and has been ignored
stage-include.bas:44: warning: [W170] Function 's_print_string_at' is never called and has been ignored
stage-include.bas:45: warning: [W170] Function 's_display_monitor' is never called and has been ignored
stage-include.bas:47: warning: [W170] Function 'fub_key_get_minutes' is never called and has been ignored
stage-include.bas:48: warning: [W170] Function 's_key_wait_for_vblank' is never called and has been ignored
stage-include.bas:49: warning: [W170] Function 's_get_key' is never called and has been ignored
...
stage-init.bas:8: warning: [W170] Function 's_stage_init' is never called and has been ignored
stage-init.bas:20: warning: [W170] Function 's_init_keyboard_table_ZX_keys' is never called and has been ignored
stage-init.bas:21: warning: [W170] Function 's_init_keyboard_table_ZX_symkeys' is never called and has been ignored
stage-init.bas:18: warning: [W170] Function 's_init_load_palette' is never called and has been ignored
stage-init.bas:186: warning: [W170] Function 's_init_load_palette_entry' is never called and has been ignored
stage-init.bas:223: warning: [W170] Function 's_init_clear_screen' is never called and has been ignored
stage-init.bas:26: warning: [W170] Function 's_init_title_screen' is never called and has been ignored

...where stage-include.bas was my attempt to make each "stage" aware of a jump-table of locations of core routines:
Asm
; fixed jump table addresses for the linker
_s_main equ $0050
_s_next_reg equ $0053
_s_return_to_zxos equ $0056
_s_crash equ $0059
_s_fc_ram_copy equ $005C
_s_clear_screen equ $005F
_s_print_char_at equ $0062
_s_print_string_at equ $0065
_s_display_monitor equ $0068
_fub_key_get_minutes equ $006B
_s_key_wait_for_vblank equ $006E
_s_get_key equ $0071
End Asm

' implementation blocks to stop "not implemented" errors
' these contain no code; the equate above handles the address
Sub s_main(): End Sub
Sub s_next_reg(reg As UByte, value As UByte): End Sub
Sub s_return_to_zxos(): End Sub
Sub s_crash(error_code As UByte, error_text As String): End Sub
Sub Fastcall s_fc_ram_copy(src_address As UInteger, dest_address As UInteger, byte_count As UInteger): End Sub
Sub s_clear_screen(): End Sub
Sub s_print_char_at(x As UByte, y As UByte, char As UByte, colour As UByte): End Sub
Sub s_print_string_at(x As UByte, y As UByte, text As String, colour As UByte): End Sub
Sub s_display_monitor(): End Sub
Function fub_key_get_minutes() As UByte: return 0: End Function
Sub s_key_wait_for_vblank(): End Sub
Sub s_get_key(): End Sub

But clearly there is something I'm not getting, and I've reached the limits of capability of AI helper tools.

I had rationalised to myself that my build script should only call to zxbc to produce "-f asm" ASM files... as I expect to have to then somehow "link" the static core ASM and the many paged stage ASM together at some point... and I also seem to have rationalised that I may perhaps need to use sjasmplus to assemble my ".nex" package.

Does the above sound achievable? Or am I asking too much of the "Next" as a platform? i.e. is the "Next" only any good for paging graphics data, and no good for paging application code?

Old zxbasic game errors

Mon, 03 Nov 2025 20:32:31 +0000

trying Escape From Cnossus from 2013 getting this error

Error: 'subdivideHigh' is neither an array nor a function.

the line is

wall1 = subdivideHigh(x1, y1, x - 1, y2)

any help please

Error: Undefined GLOBAL label

Sun, 02 Nov 2025 12:43:21 +0000

Looking over an old file of mine that once worked I'm now getting Error: Undefined GLOBAL label . each one is going to a fastcall.

ie

ld hl, lineMSG
ld bc, end1-lineMSG
call myPrint42

calling

SUB fastcall myPrint42()
ASM
myPrint42:
push af
push ix
push hl
ld ix, PRINT42
CALL IXCALL
pop hl
pop ix
pop af
ret
END ASM
END SUB

gives me Error: Undefined GLOBAL label ".myPrint42"

any help please....

A Fast(er) Plot Routine for Boriel Basic

Tue, 28 Oct 2025 14:56:34 +0000

I orginally posted this on SpectrumComputing Forum - copied here in case anyone wants to play with it :-)

Hi

Hope this helps someone else :-)

I saw a post by Andy Dansby who writes at https://zxspectrumcoding.wordpress.com/

He has created a fast plot routine, (hellaplot), so I thought I'd try and convert it to a Boriel Basic (BB) subroutine, just for fun and learning - and as it was a single routine.

I had to do a little bit of reading, but also had to ask for help from the BB telegram community, as to begin with the code was crashing the emulator. Turns out it was a simple fix when you know how - FASTCALL was needed when passing parameters for ASM to use from a SUB routine.

Andy's code needs the x/y locations in DE, so I had to do a little bit to get them set up like this - I assume there might be some more efficiency if different registers were used as BB passes from the subroutine call, the first parameter into A, and the second parameter is the second item on the stack (the first being the return address).

When I started, xPos was the first parameter, and yPos the second (as I like x,y), but this meant to get them into DE, took another load (POP DE, LD E with D, LD D with A, compared to POP DE, LD E with A)

So some "non exact" timings - plot included as the library in BB takes about 15 seconds to fill up the screen with "points". Andy's one takes 5 seconds to do the same.

As far as Andy's code goes, I understand the comments, but not exactly how it works :-)

Anyway, code below :

SUB FASTCALL HellaPrint(yPos as UBYTE, xPos as UBYTE)
' HellaPrint prints an x,y pixel
' 0,0 is top left
' Original code by Andy Lansby
' https://zxspectrumcoding.wordpress.com/
' yPos is first, as it save a LD instruction when putting xPos and yPos into DE
ASM

JP START ; Put this in as it's like this on the Wiki ASM desciption - can it be avoided?
X_PositionBits: defb 128,64,32,16,8,4,2,1
; Might there be a quicker way to do the above, so it's not needed every time the program is run? or does it not work like this and is created once at compile time?

START: ; plot d = x-axis, e = y-axis
; A contains the yPos, xPos is on stack.
POP HL ; Pops the return address into HL
POP DE ; xPos is on the stack, and it needs to be in D
LD E, A ; A has our first paramter (yPos), load it into E. D should be Xpos, E should be yPos
PUSH HL ; Puts the return address back onto stack ...
; 166 T states per pixel
XOR A ; reset A to 0 and flags to default
LD A,E ; load Y plot point
RRA ; rotate Right --- divide in half
SCF ; turn on Carry flag-
RRA ; rotate right with the carry flag
OR A ; set flag S on - C flag off
RRA ; rotate Right --- divide in half

LD L,A ; temp store in L
XOR E ; XOR the Y value
AND %11111000 ; mask out bottom 3 bits
XOR E ; XOR the Y value

LD H,A ; store High byte
LD A,D ; load X plot point
XOR L ; XOR the temp value
AND %00000111 ; mask out unwanted bits
XOR D ; XOR the X value
RRCA ; divide by 2
RRCA ; divide by 4
RRCA ; divide by 8

LD L,A ; store Low byte
; now we have the full address
; now use LUT to find which bit to set
LD A,D ; load X plot point
AND %00000111 ; mask out unwanted bits

; use a LUT to quickly find the bit position for the X position
LD DE,X_PositionBits ; load LUT address into DE
ADD A,E ; Add A to E to get offset into table
LD E,A ; E now points to the LUT entry
LD A,(DE) ; load answer into A

; output to screen
OR (HL) ; or with contents of address HL
LD (HL),A ; load address HL with Answer from A
END ASM
END SUB

Hall of Fame - Include for ZX Basic

Tue, 28 Oct 2025 14:48:44 +0000

Hi

HOF.zxbas - Hall of fame procedures
main.zxbas - a demo

Attached is a little "library" for a Hall of Fame / High Score table.

To use it - you need to create two Arrays (at least 2 ...)

Array 1 = UInteger, for scores
Array 2 = String, for names

Probably best to keep to 10 entries, but could be more. You can have more than 1 HOF, so could have Array2, Arry3 etc etc for say Easy Score, Medium Scores, Hard Scores. As it passes the Arrays by reference, no other variables are needed.

Completely and utterly free to use, adapt, change, republish how ever you want.

Arraybase is 0

SUB HOF_IntialiseHOF(BYREF HOF_Scores() AS UINTEGER, BYREF HOF_Names() AS STRING, HOF_IntialTopScore as UINTEGER,HOF_InitialName AS STRING)
Use this to initialise the two HOF arrays - with a "highest score, working down to a low score and gives each entry "InitialName".

FUNCTION HOF_HighScore_CheckEntry (HOF_Scores() AS UINTEGER, NewHighScore as UINTEGER) AS BYTE
Returns 1 if the High Score can g into the Arrays.

SUB HOF_HighScore_NewEntry (BYREF HOF_Scores() AS UINTEGER, BYREF HOF_Names() AS STRING, NewHighScore as UINTEGER, NewHighScoreName AS STRING)
Puts the new entries (name & score) into the HOF array.

SUB HOF_Print(BYREF HOF_Scores() AS UINTEGER, BYREF HOF_Names() AS STRING, YPOS as INTEGER, XPOS as INTEGER)
A simple print location, witch prints the Score and Names. Will carry on printing if you have many entries ...

SUB HOF_PrintSpecial(BYREF HOF_Scores() AS UINTEGER, BYREF HOF_Names() AS STRING)
A "pretty High Score screen", that prints the top 10 scores.

Can probably be improved and made much more efficient. There are porbably bugs as well (for example not sure what would happen if you had 100 entries with a first high score of 10 ... i think it's probably overflow to 655555 etc. It includes string.bas and input.bas - not sure if the library needs both of those.

HOF.zip (Size: 2.98 KB / Downloads: 164)

Hall Of Fame.png (Size: 2.13 KB / Downloads: 258)

[SOLVED] Array layout bug - regression in 1.18.3

Fri, 24 Oct 2025 22:24:41 +0000

Please take a look at this simple programme:

Code:
dim a(5) as ubyte => {0, 1, 2, 3, 4, 5}
dim b(5) as ubyte
dim i as uinteger

for i = 0 to 5
    poke @b + i, a(i)
next

cls

for i = 0 to 5
    print a(i), b(i)
next

When compiled with zxbasic 1.18.2 this works as expected - both arrays are same. See the attached image:

arrays_zxbasic_1_18_2.png (Size: 8.81 KB / Downloads: 243)
However, with zxbasic 1.18.3, the programme fails miserably and crashes the Spectrum

In both cases compiled with

Quote: Wrote:--optimize 2 --output-format=tzx --BASIC --autorun --explicit --strict

Now, this is the simple case made to illustrate the bug. The main problem I have is with character arrays -- I have custom font with cyrilic letters designed in ZXBasicStudio, stored as two dimensional array (95, 7) -- when I want to write cyrilic text I poke the system variable 5C36 to the address of the array minus 256 (@array - $100) and when I want to print latin text, I just poke this variable back to default value $3C00. This worked perfectly until version 1.18.3 came out. Now, everything is broken, as the characters in the array are obviously not stored continuously in memory.
What happend with array layout?

Now I tried to see the address of the array itself, compared with the addresses of array elements:

Code:
dim a(5) as ubyte => {0, 1, 2, 3, 4, 5}
dim i as uinteger
cls
print "@a = "; @a
print "------------"
for i = 0 to 5
  print "@a("; i; ") = "; @a(i)
next

The attached image shows the output with zxbasic 1.18.2 compared with zxbasic 1.18.3:

arrayAddresses.png (Size: 14.42 KB / Downloads: 282)

It seems that in zxbasic 1.18.3, there are eight bytes between the address of the array itself (@a) and the first element (@a(0) ). The array elements are stored continuously after all.

So, I can workaround the problem with the custom character set that I mentioned in my previous post using:

Code:
poke (uinteger $5c36, @charset(0,0) - $100) ' the address of the first element

instead of

Code:
poke (uinteger $5c36, @charset - $0100) ' the address of the array

But still, is there a reason for this, or is it just a bug?

3DOS Commands?

Sun, 05 Oct 2025 21:33:54 +0000

Hi

I'm looking at using some 3DOS commands, starting to see how I can cat a disk.

I've takend the below code from the +3 manula (pg 200 to 203) which should allow me to get the CAT into memory - the code looks to activate the disk (and for example if I don't attach a disk, it give me abort/retry) but then "reboots"/crashes the emulator back to the +3 menu.

I'm assuming that there might be some incompatibility somewhere between, starting reading, and returning contorl to the program. Code is below.

Any thoughts?

(PS If the ASM didn't crash, the program wouldn't actually do anything anyway yet, as I've not sorted any output, or any caribles)

Code:
#include 
#include 
#INCLUDE  

PRINT "This is the start"
main()


SUB main()
    LET YesNo = "n"
    PRINT "do you want to CAT disk"
    YesNo = INPUT(1)
    IF YesNo="y" then
        Catalogue()
    END IF
    PRINT "Ed#nd Main"
END SUB



SUB Catalogue()
    ASM
        PUSH IX ; dos catalog corrupts ix
        PROC
        
        LOCAL   MYSTACK
        LOCAL   STACKSTORAGE
        LOCAL   BANKM
        LOCAL   PORT1
        LOCAL   CATBUFF
        LOCAL   DOS_CATALOG
        
        
        MYSTACK         EQU     9fffh ; 
        STACKSTORAGE    EQU     9000h ; save pointer
        BANKM           EQU     5b5ch ; system var that holds last value output to 7ff0h
        PORT1           EQU     7ffdh ; address of rom/ram switching port
        CATBUFF         EQU     8000h ; location for dos to output
        DOS_CATALOG     EQU     011Eh ; DOS routine to call
    
        JP start
        stardstar:  defb "*.*",255                    
        dosret:     defw 0
    
        start:
            DI
            LD (STACKSTORAGE),SP
            LD BC,PORT1         ; 
            LD A,(BANKM)        ; current switch state
            RES 4,A             ; move right to left in horizontal rom switch (3 to 2)
            OR 7                ; switch in ram page 7
            LD (BANKM),A        ; keep system var up to date
            OUT (C),A           ; switch ram and rom
            LD SP,MYSTACK       ; make sure stack is above 4000h and below bfeoh
            EI                  ; enable interrupts
            ; 
    
   
            LD HL,CATBUFF
            LD DE,CATBUFF+1
            LD BC,1024
            LD (HL),0
            LDIR
            LD B,64
            LD C,1
            LD DE, CATBUFF
            LD HL,stardstar             ;file name *.*
            CALL DOS_CATALOG            ;call dos catalog
            PUSH AF
            POP HL
            LD (dosret),HL              ; put here so can be seen from basic
            LD C,B                      ; number of files in catalog, low byte of bc
            LD B,0                      ; returned to basic by usr functio
    
            DI
            PUSH BC
            LD BC, PORT1
            LD A, (BANKM)
            SET 4, A                    ; move left to right (riom 2 to 3)
            AND 48h                     ; ram page 9
            LD (BANKM),A                ; update syste value
            OUT (C),A                   ;switch
            POP BC                      ; get back saved number of files
            LD SP,(STACKSTORAGE)        ; 
            EI
            ;RET ; not sure if thisis needed
        ENDP
        POP IX
        ;RET ; Not sure if this is needed here
    END ASM
END SUB