Isomorphic BASIC cross compiler

version 1.16.4

This User Manual refers to this specific version only. While every care has
been taken to ensure the correctness of informations present in this book and
on the software, it is not guaranteed that they will be valid for previous or
successive versions. The author cannot be held responsible for any errors or
omissions. If you do find any, please contact the author using GitHub or the
Official Forum.

This book is updated periodically, inserting corrections, new commands, tu-

torials and new explanations: please, respect the environment and do not
print it on paper: thank you!
ugBASIC, UGBASIC-IDE and manual ©2021-2024 Marco Spedaletti.

Book revision: a21c2fe94 - October 26, 2024

The ugBASIC software is licensed under the Apache License 2.0, which
allows you to modify, distribute, and sublicense the original open source
code.

Commercial use of the software is also permitted, as long as you include

the original copyright notice, a copy of the license text, and the attri-
bution notices, including any significant changes to the original code.

Games and programs made with the ugBASIC software may be licensed
under any license, as long as their authors acknowledge the use of
ugBASIC in the development of the program.

Official website:
https://ugbasic.iwashere.eu/

ugBASIC repository:
https://github.com/spotlessmind1975/ugbasic

Official forum:
https://forum.ugbasic.iwashere.eu/

4
Contents

1 Introduction 31
1.1 Welcome! . . . . . . . . . . . . . . . . . . . . . . 31
1.2 Features . . . . . . . . . . . . . . . . . . . . . . . 32
1.3 Games . . . . . . . . . . . . . . . . . . . . . . . . 33
1.4 Beta version . . . . . . . . . . . . . . . . . . . . . 35
1.5 What is isomorphism? . . . . . . . . . . . . . . . . 36

2 Getting started 39
2.1 Using sandbox . . . . . . . . . . . . . . . . . . . . 40
2.2 Install ugBASIC . . . . . . . . . . . . . . . . . . . 41
2.2.1 Choose your target . . . . . . . . . . . . . . . 42
2.2.2 Download the compiler . . . . . . . . . . . . . 43
2.2.3 Download additional software . . . . . . . . . . 44
2.2.4 Configure the path . . . . . . . . . . . . . . . 45
On Microsoft Windows . . . . . . . . . . . . . 45
On Linux . . . . . . . . . . . . . . . . . . . . . 46
2.2.5 Verify the installation . . . . . . . . . . . . . . 46
2.3 Install UGBASIC-IDE . . . . . . . . . . . . . . . . 48

3 ”BASIC” concepts 49
3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . 50
3.1.1 Keywords . . . . . . . . . . . . . . . . . . . . 50
3.1.2 Identifiers . . . . . . . . . . . . . . . . . . . . 52
3.1.3 Statements . . . . . . . . . . . . . . . . . . . 53

5
Contents

3.1.4 Split (long) lines . . . . . . . . . . . . . . . . . 53

3.1.5 Comments . . . . . . . . . . . . . . . . . . . . 53
3.1.6 White spaces . . . . . . . . . . . . . . . . . . 54
3.1.7 Labels (and line numbers) . . . . . . . . . . . 55
3.1.8 Hash operator . . . . . . . . . . . . . . . . . . 55
3.1.9 Buffer definition . . . . . . . . . . . . . . . . . 56
3.1.10 Assignment . . . . . . . . . . . . . . . . . . . 56
By copy . . . . . . . . . . . . . . . . . . . . . 56
By reference . . . . . . . . . . . . . . . . . . . 57
3.1.11 Abbreviations . . . . . . . . . . . . . . . . . . 57
3.1.12 Conditional compilation . . . . . . . . . . . . . 58
3.2 Data types . . . . . . . . . . . . . . . . . . . . . . 60
3.2.1 Integers . . . . . . . . . . . . . . . . . . . . . 60
3.2.2 Numbers and numerals . . . . . . . . . . . . . 63
3.2.3 Floating point . . . . . . . . . . . . . . . . . . 64
3.2.4 Bits . . . . . . . . . . . . . . . . . . . . . . . 65
3.2.5 Strings . . . . . . . . . . . . . . . . . . . . . . 65
3.2.6 Resources and buffers . . . . . . . . . . . . . . 66
3.3 Variables and constants . . . . . . . . . . . . . . . 69
3.3.1 Variables . . . . . . . . . . . . . . . . . . . . . 69
3.3.2 Variables scope . . . . . . . . . . . . . . . . . 70
3.3.3 Constants . . . . . . . . . . . . . . . . . . . . 71
3.3.4 Asserting using constants . . . . . . . . . . . . 71
3.3.5 Type conversion (casting) . . . . . . . . . . . . 72
3.4 Strings . . . . . . . . . . . . . . . . . . . . . . . . 73
3.4.1 Extracting and replacing chars . . . . . . . . . 73
3.4.2 Finding characters in a string . . . . . . . . . . 74
3.4.3 Converting strings . . . . . . . . . . . . . . . . 75
3.4.4 Manipulating strings . . . . . . . . . . . . . . . 76
3.4.5 Getting information about strings . . . . . . . . 76
3.5 Arrays . . . . . . . . . . . . . . . . . . . . . . . . 77
3.5.1 Defining an array . . . . . . . . . . . . . . . . 77
3.5.2 Bounds of an array . . . . . . . . . . . . . . . 78
3.5.3 Type an array . . . . . . . . . . . . . . . . . . 79
3.5.4 Initialize an array . . . . . . . . . . . . . . . . 80

6
 Contents

3.5.5 Filling an array . . . . . . . . . . . . . . . . . 82

3.6 Maths . . . . . . . . . . . . . . . . . . . . . . . . 83
3.6.1 Arithmetical calculations . . . . . . . . . . . . 83
3.6.2 Calculation priorities . . . . . . . . . . . . . . . 85
3.6.3 Fast calculations . . . . . . . . . . . . . . . . . 86
3.6.4 Relative values . . . . . . . . . . . . . . . . . . 88
3.6.5 Values and signs . . . . . . . . . . . . . . . . . 88
3.6.6 Random numbers . . . . . . . . . . . . . . . . 90
3.7 Control structures . . . . . . . . . . . . . . . . . . 91
3.7.1 Unconditional jumps . . . . . . . . . . . . . . 91
3.7.2 Returning from jumps . . . . . . . . . . . . . . 92
3.7.3 Popping returning addresses . . . . . . . . . . 93
3.7.4 Decision making . . . . . . . . . . . . . . . . . 94
3.7.5 Loops and repetitions . . . . . . . . . . . . . . 96
3.7.6 Controlled loops . . . . . . . . . . . . . . . . . 99
3.7.7 Forced jumps by expression . . . . . . . . . . . 99
3.7.8 Periodic calls . . . . . . . . . . . . . . . . . . 101
3.8 Procedures . . . . . . . . . . . . . . . . . . . . . . 102
3.8.1 Creating a procedure . . . . . . . . . . . . . . 102
3.8.2 Jumping in and out of a procedure . . . . . . . 103
3.8.3 Local and global variables . . . . . . . . . . . . 105
3.8.4 Parameters passing . . . . . . . . . . . . . . . 106

4 Texts 109
4.1 Printing on the console . . . . . . . . . . . . . . . 110
4.2 Setting text options . . . . . . . . . . . . . . . . . 111
4.3 Positioning the text cursor . . . . . . . . . . . . . . 112
4.4 Erasing text . . . . . . . . . . . . . . . . . . . . . 116
4.5 Tracking the text cursor . . . . . . . . . . . . . . . 116
4.6 Defining a console . . . . . . . . . . . . . . . . . . 117

5 Graphics 121
5.1 Enable the bitmap mode . . . . . . . . . . . . . . 122
5.2 Plot a pixel on screen . . . . . . . . . . . . . . . . 123
5.3 Implicit vs explicit colors . . . . . . . . . . . . . . . 124

7
Contents

5.4 Retrieve the color of a pixel . . . . . . . . . . . . . 124

5.5 Using the graphic cursor . . . . . . . . . . . . . . . 125
5.6 Clipping the coordinates . . . . . . . . . . . . . . . 125
5.7 Relative vs absolute coordinates . . . . . . . . . . . 126
5.8 Drawing lines . . . . . . . . . . . . . . . . . . . . . 126
5.9 Styling lines . . . . . . . . . . . . . . . . . . . . . 127
5.10 Selecting colors . . . . . . . . . . . . . . . . . . . 127
5.11 Drawing connected lines . . . . . . . . . . . . . . . 128
5.12 Drawing boxes . . . . . . . . . . . . . . . . . . . . 129
5.13 Drawing circles and ellipses . . . . . . . . . . . . . 129
5.14 Advanced topics . . . . . . . . . . . . . . . . . . . 130
5.14.1 Raster graphic . . . . . . . . . . . . . . . . . . 130

6 Images 133
6.1 Loading images . . . . . . . . . . . . . . . . . . . 134
6.2 Drawing images . . . . . . . . . . . . . . . . . . . 136
6.3 Flipping images . . . . . . . . . . . . . . . . . . . 138
6.4 Loading atlas . . . . . . . . . . . . . . . . . . . . . 139
6.5 Loading sequences . . . . . . . . . . . . . . . . . . 140
6.6 Transparency . . . . . . . . . . . . . . . . . . . . . 141
6.7 Getting images . . . . . . . . . . . . . . . . . . . . 141
6.8 Advanced topics . . . . . . . . . . . . . . . . . . . 142
6.8.1 What is a buffer? . . . . . . . . . . . . . . . . 142
6.8.2 So, what is an image? . . . . . . . . . . . . . . 143
6.8.3 Beyond transparency . . . . . . . . . . . . . . 143

7 Blitting operations 145

7.1 A bit of history . . . . . . . . . . . . . . . . . . . . 146
7.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . 146
7.3 A preliminary example . . . . . . . . . . . . . . . . 148
7.4 A bit of theory . . . . . . . . . . . . . . . . . . . . 151
7.4.1 How unary operations work . . . . . . . . . . . 152
7.4.2 How binary operations works . . . . . . . . . . 155
7.5 How to use it . . . . . . . . . . . . . . . . . . . . 158
7.6 Limitations . . . . . . . . . . . . . . . . . . . . . . 159

8
 Contents

8 Sprites 161
8.1 Basic commands . . . . . . . . . . . . . . . . . . . 162
8.2 Composite sprites . . . . . . . . . . . . . . . . . . 163
8.3 Multiplexed sprites . . . . . . . . . . . . . . . . . . 164
8.4 Redefining sprites . . . . . . . . . . . . . . . . . . 167
8.5 Sprite palette . . . . . . . . . . . . . . . . . . . . . 167
8.6 Coordinates . . . . . . . . . . . . . . . . . . . . . 168

9 I/O Controls 171

9.1 Using the joystick . . . . . . . . . . . . . . . . . . 172
9.1.1 Reading directions . . . . . . . . . . . . . . . . 172
9.1.2 Asynchronous vs syncronous readings . . . . . 175
9.2 Using the Keyboard . . . . . . . . . . . . . . . . . 176
9.2.1 Basic commands . . . . . . . . . . . . . . . . . 176
9.2.2 State of keys . . . . . . . . . . . . . . . . . . . 178
9.2.3 More input . . . . . . . . . . . . . . . . . . . . 181
9.2.4 Other settings . . . . . . . . . . . . . . . . . . 182
9.2.5 Asynchronous vs syncronous readings . . . . . 184
9.2.6 Some theorical aspects . . . . . . . . . . . . . 185

10 Audio and music support 189

10.1 Basic effects . . . . . . . . . . . . . . . . . . . . . 190
10.2 Musical notes . . . . . . . . . . . . . . . . . . . . 195
10.3 Channels and voices . . . . . . . . . . . . . . . . . 195
10.4 Playing notes . . . . . . . . . . . . . . . . . . . . . 196
10.5 Instruments . . . . . . . . . . . . . . . . . . . . . 198
10.6 Playing music . . . . . . . . . . . . . . . . . . . . 198
10.6.1 Play MIDI soundtracks . . . . . . . . . . . . . 198
10.6.2 Play SJ2 soundtracks . . . . . . . . . . . . . . 199
10.6.3 Play PSG soundtracks . . . . . . . . . . . . . . 200

11 Expansion memory 201

11.1 Banked expansion memory . . . . . . . . . . . . . 202
11.1.1 How it works . . . . . . . . . . . . . . . . . . 202
11.1.2 Shared resident memory . . . . . . . . . . . . . 203

9
Contents

11.1.3 Multiple shared resident memory . . . . . . . . 204

11.1.4 Loading resource . . . . . . . . . . . . . . . . 205
11.1.5 Loading resource on separate shared memory . 206
11.1.6 Defining arrays on expansion memory . . . . . 206
11.2 DMA expanded memory . . . . . . . . . . . . . . . 207
11.2.1 Loading resource on expansion . . . . . . . . . 208
11.2.2 Defining arrays on expansion memory . . . . . 208

12 Mass storage support 211

12.1 Loading a string . . . . . . . . . . . . . . . . . . . 211
12.2 Loading an image . . . . . . . . . . . . . . . . . . 213
12.3 Loading an atlas . . . . . . . . . . . . . . . . . . . 214

13 Multitasking 215
13.1 Defining parallel procedures . . . . . . . . . . . . . 216
13.2 Deciding the right moment . . . . . . . . . . . . . 217
13.3 Simple synchronization . . . . . . . . . . . . . . . 218
13.4 Kill a thread . . . . . . . . . . . . . . . . . . . . . 219
13.5 Using (local) variables . . . . . . . . . . . . . . . . 219
13.6 Enable and disable . . . . . . . . . . . . . . . . . . 221

14 Assembly 223
14.1 Loading object code . . . . . . . . . . . . . . . . . 224
14.2 Passing parameters and return values . . . . . . . . 225
14.2.1 Using registers . . . . . . . . . . . . . . . . . . 225
14.2.2 Using stack . . . . . . . . . . . . . . . . . . . 226
14.3 Portable assembly code . . . . . . . . . . . . . . . 228
14.4 Inlining assembly code . . . . . . . . . . . . . . . . 230
14.5 Importing procedures and functions . . . . . . . . . 231
14.6 System functions . . . . . . . . . . . . . . . . . . . 234

15 Keywords 235
15.1 $$ . . . . . . . . . . . . . . . . . . . . . . . . . . 236
15.2 %% . . . . . . . . . . . . . . . . . . . . . . . . . . 237
15.3 ABS . . . . . . . . . . . . . . . . . . . . . . . . . 238

10
 Contents

15.4 ADD . . . . . . . . . . . . . . . . . . . . . . . . . 239

15.5 ADDRESS (data type) . . . . . . . . . . . . . . . 240
15.6 AFTER...CALL . . . . . . . . . . . . . . . . . . . . 241
15.7 AFTER...GOSUB . . . . . . . . . . . . . . . . . . 243
15.8 ALLOW . . . . . . . . . . . . . . . . . . . . . . . 244
15.9 ALT LEFT (constant) . . . . . . . . . . . . . . . . 246
15.10 ALT RIGHT (constant) . . . . . . . . . . . . . . . 247
15.11 AND . . . . . . . . . . . . . . . . . . . . . . . . . 248
15.12 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . 250
15.13 ARROW LEFT (constant) . . . . . . . . . . . . . . 251
15.14 ARROW UP (constant) . . . . . . . . . . . . . . . 252
15.15 ASC . . . . . . . . . . . . . . . . . . . . . . . . . 253
15.16 ASCII CODE . . . . . . . . . . . . . . . . . . . . . 255
15.17 ASCIICODE . . . . . . . . . . . . . . . . . . . . . 257
15.18 ASM . . . . . . . . . . . . . . . . . . . . . . . . . 258
15.19 ASTERISK (constant) . . . . . . . . . . . . . . . . 260
15.20 AT (constant) . . . . . . . . . . . . . . . . . . . . 261
15.21 AT (function) . . . . . . . . . . . . . . . . . . . . 262
15.22 AT (instruction) . . . . . . . . . . . . . . . . . . . 263
15.23 ATLAS (data type) . . . . . . . . . . . . . . . . . 264
15.24 ATLAS LOAD . . . . . . . . . . . . . . . . . . . . 265
15.25 BANK . . . . . . . . . . . . . . . . . . . . . . . . 266
15.26 BANK (function) . . . . . . . . . . . . . . . . . . 267
15.27 BANK ADDRESS . . . . . . . . . . . . . . . . . . 268
15.28 BANK COUNT (constant) . . . . . . . . . . . . . 269
15.29 BANK READ . . . . . . . . . . . . . . . . . . . . 270
15.30 BANK WRITE . . . . . . . . . . . . . . . . . . . . 271
15.31 BANK...AT . . . . . . . . . . . . . . . . . . . . . . 272
15.32 BAR . . . . . . . . . . . . . . . . . . . . . . . . . 273
15.33 BEGIN GAMELOOP . . . . . . . . . . . . . . . . . 274
15.34 BEGIN STORAGE . . . . . . . . . . . . . . . . . . 276
15.35 BELL . . . . . . . . . . . . . . . . . . . . . . . . . 277
15.36 BETA (constant) . . . . . . . . . . . . . . . . . . 279
15.37 BIG ENDIAN (constant) . . . . . . . . . . . . . . . 280
15.38 BIN . . . . . . . . . . . . . . . . . . . . . . . . . . 282

11
Contents

15.39 BIT (data type) . . . . . . . . . . . . . . . . . . . 283

15.40 BIT (function) . . . . . . . . . . . . . . . . . . . . 284
15.41 BIT...OF . . . . . . . . . . . . . . . . . . . . . . . 285
15.42 BITMAP (constant) . . . . . . . . . . . . . . . . . 286
15.43 BITMAP AT . . . . . . . . . . . . . . . . . . . . . 287
15.44 BITMAP CLEAR . . . . . . . . . . . . . . . . . . 288
15.45 BITMAP DISABLE . . . . . . . . . . . . . . . . . 289
15.46 BITMAP ENABLE . . . . . . . . . . . . . . . . . . 290
15.47 BLACK (constant) . . . . . . . . . . . . . . . . . . 292
15.48 BLIT (data type) . . . . . . . . . . . . . . . . . . 293
15.49 BLIT (instruction) . . . . . . . . . . . . . . . . . . 294
15.50 BLIT IMAGE . . . . . . . . . . . . . . . . . . . . . 295
15.51 BLOCK . . . . . . . . . . . . . . . . . . . . . . . . 296
15.52 BLUE (constant) . . . . . . . . . . . . . . . . . . . 297
15.53 BOOM . . . . . . . . . . . . . . . . . . . . . . . . 298
15.54 BORDER . . . . . . . . . . . . . . . . . . . . . . . 299
15.55 BOX . . . . . . . . . . . . . . . . . . . . . . . . . 300
15.56 BROWN (constant) . . . . . . . . . . . . . . . . . 301
15.57 BUFFER (data type) . . . . . . . . . . . . . . . . 302
15.58 BYTE (data type) . . . . . . . . . . . . . . . . . . 303
15.59 CALL . . . . . . . . . . . . . . . . . . . . . . . . . 304
15.60 CAN SCREEN . . . . . . . . . . . . . . . . . . . . 306
15.61 CAPS LOCK (constant) . . . . . . . . . . . . . . . 307
15.62 CAPSLOCK (constant) . . . . . . . . . . . . . . . 308
15.63 CASE . . . . . . . . . . . . . . . . . . . . . . . . . 309
15.64 CASE ELSE . . . . . . . . . . . . . . . . . . . . . 310
15.65 CDOWN (function) . . . . . . . . . . . . . . . . . 311
15.66 CDOWN (instruction) . . . . . . . . . . . . . . . . 312
15.67 CENTER . . . . . . . . . . . . . . . . . . . . . . . 313
15.68 CENTRE . . . . . . . . . . . . . . . . . . . . . . . 314
15.69 CGOTO . . . . . . . . . . . . . . . . . . . . . . . 315
15.70 CHARSET AT . . . . . . . . . . . . . . . . . . . . 316
15.71 CHR$ . . . . . . . . . . . . . . . . . . . . . . . . . 317
15.72 CIRCLE . . . . . . . . . . . . . . . . . . . . . . . 318
15.73 CLEAR . . . . . . . . . . . . . . . . . . . . . . . . 319

12
 Contents

15.74 CLEAR (constant) . . . . . . . . . . . . . . . . . . 320

15.75 CLEFT (function) . . . . . . . . . . . . . . . . . . 321
15.76 CLEFT (instruction) . . . . . . . . . . . . . . . . . 322
15.77 CLINE . . . . . . . . . . . . . . . . . . . . . . . . 323
15.78 CLIP . . . . . . . . . . . . . . . . . . . . . . . . . 324
15.79 CLS . . . . . . . . . . . . . . . . . . . . . . . . . . 325
15.80 CMOB . . . . . . . . . . . . . . . . . . . . . . . . 327
15.81 CMOVE (function) . . . . . . . . . . . . . . . . . 328
15.82 CMOVE (instruction) . . . . . . . . . . . . . . . . 329
15.83 COLLISION . . . . . . . . . . . . . . . . . . . . . 330
15.84 COLOR . . . . . . . . . . . . . . . . . . . . . . . . 331
15.85 COLOR (data type) . . . . . . . . . . . . . . . . . 333
15.86 COLOR (function) . . . . . . . . . . . . . . . . . . 334
15.87 COLOR BACK . . . . . . . . . . . . . . . . . . . . 335
15.88 COLOR BACKGROUND . . . . . . . . . . . . . . 336
15.89 COLOR BORDER . . . . . . . . . . . . . . . . . . 337
15.90 COLOR COUNT (constant) . . . . . . . . . . . . . 339
15.91 COLOR SPRITE . . . . . . . . . . . . . . . . . . . 340
15.92 COLORMAP AT . . . . . . . . . . . . . . . . . . . 341
15.93 COLORMAP CLEAR . . . . . . . . . . . . . . . . 342
15.94 COLORS (constant) . . . . . . . . . . . . . . . . . 343
15.95 COLORS COUNT (constant) . . . . . . . . . . . . 344
15.96 COLOUR . . . . . . . . . . . . . . . . . . . . . . . 345
15.97 COLOURS (constant) . . . . . . . . . . . . . . . . 346
15.98 COLOURS COUNT (constant) . . . . . . . . . . . 347
15.99 COLUMNS (constant) . . . . . . . . . . . . . . . . 348
15.100 COMBINE NIBBLE . . . . . . . . . . . . . . . . . 349
15.101 CONFIGURE . . . . . . . . . . . . . . . . . . . . . 350
15.102 CONSOLE . . . . . . . . . . . . . . . . . . . . . . 351
15.103 CONSOLE RESTORE . . . . . . . . . . . . . . . . 352
15.104 CONSOLE SAVE . . . . . . . . . . . . . . . . . . 353
15.105 CONSOLE USE . . . . . . . . . . . . . . . . . . . 354
15.106 CONST . . . . . . . . . . . . . . . . . . . . . . . 355
15.107 CONST GLOBAL . . . . . . . . . . . . . . . . . . 357
15.108 CONST SHARED . . . . . . . . . . . . . . . . . . 358

13
Contents

15.109 CONTROL (constant) . . . . . . . . . . . . . . . . 359

15.110 COS . . . . . . . . . . . . . . . . . . . . . . . . . 360
15.111 CREATE PORT . . . . . . . . . . . . . . . . . . . 361
15.112 CRIGHT (function) . . . . . . . . . . . . . . . . . 362
15.113 CRIGHT (instruction) . . . . . . . . . . . . . . . . 363
15.114 CRSR LEFT RIGHT (constant) . . . . . . . . . . . 364
15.115 CRSR UP DOWN (constant) . . . . . . . . . . . . 365
15.116 CSET . . . . . . . . . . . . . . . . . . . . . . . . . 366
15.117 CSPRITE . . . . . . . . . . . . . . . . . . . . . . . 367
15.118 CUP (function) . . . . . . . . . . . . . . . . . . . 369
15.119 CUP (instruction) . . . . . . . . . . . . . . . . . . 370
15.120 CYAN (constant) . . . . . . . . . . . . . . . . . . 371
15.121 D!POKE . . . . . . . . . . . . . . . . . . . . . . . 372
15.122 DARK BLUE (constant) . . . . . . . . . . . . . . . 373
15.123 DARK GRAY (constant) . . . . . . . . . . . . . . . 374
15.124 DARK GREY (constant) . . . . . . . . . . . . . . . 375
15.125 DATA . . . . . . . . . . . . . . . . . . . . . . . . 376
15.126 DEC . . . . . . . . . . . . . . . . . . . . . . . . . 378
15.127 DECLARE FUNCTION . . . . . . . . . . . . . . . 379
15.128 DECLARE PROC . . . . . . . . . . . . . . . . . . 380
15.129 DECLARE PROCEDURE . . . . . . . . . . . . . . 381
15.130 DEFDGR . . . . . . . . . . . . . . . . . . . . . . . 383
15.131 DEGREE . . . . . . . . . . . . . . . . . . . . . . . 384
15.132 DELETE (constant) . . . . . . . . . . . . . . . . . 385
15.133 DESTROY PORT . . . . . . . . . . . . . . . . . . 386
15.134 DIM (array) . . . . . . . . . . . . . . . . . . . . . 387
15.135 DIM (variable) . . . . . . . . . . . . . . . . . . . . 389
15.136 DISABLE INTERRUPT . . . . . . . . . . . . . . . 391
15.137 DISTANCE . . . . . . . . . . . . . . . . . . . . . . 392
15.138 DIV . . . . . . . . . . . . . . . . . . . . . . . . . . 393
15.139 DLOAD . . . . . . . . . . . . . . . . . . . . . . . 394
15.140 DLOAD ERROR . . . . . . . . . . . . . . . . . . . 396
15.141 DO NULL . . . . . . . . . . . . . . . . . . . . . . 397
15.142 DO...LOOP . . . . . . . . . . . . . . . . . . . . . 398
15.143 DOJO CREATE PORT . . . . . . . . . . . . . . . 399

14
 Contents

15.144 DOJO DESTROY PORT . . . . . . . . . . . . . . 400

15.145 DOJO FIND PORT . . . . . . . . . . . . . . . . . 401
15.146 DOJO GET MESSAGE . . . . . . . . . . . . . . . 402
15.147 DOJO LOGIN . . . . . . . . . . . . . . . . . . . . 403
15.148 DOJO PEEK MESSAGE . . . . . . . . . . . . . . 404
15.149 DOJO PING . . . . . . . . . . . . . . . . . . . . . 405
15.150 DOJO PUT MESSAGE . . . . . . . . . . . . . . . 406
15.151 DOJO READY . . . . . . . . . . . . . . . . . . . . 407
15.152 DOJO RECEIVE . . . . . . . . . . . . . . . . . . . 408
15.153 DOJO SEND . . . . . . . . . . . . . . . . . . . . . 409
15.154 DOJO SUCCESS . . . . . . . . . . . . . . . . . . 410
15.155 DOJOKA (data type) . . . . . . . . . . . . . . . . 411
15.156 DOUBLE BUFFER . . . . . . . . . . . . . . . . . 412
15.157 DOWN (constant) . . . . . . . . . . . . . . . . . . 414
15.158 DRAW (instruction) . . . . . . . . . . . . . . . . . 415
15.159 DRAW (program) . . . . . . . . . . . . . . . . . . 417
15.160 DSAVE . . . . . . . . . . . . . . . . . . . . . . . . 419
15.161 DSAVE ERROR . . . . . . . . . . . . . . . . . . . 420
15.162 DTILE . . . . . . . . . . . . . . . . . . . . . . . . 421
15.163 DTILES . . . . . . . . . . . . . . . . . . . . . . . 422
15.164 DUP . . . . . . . . . . . . . . . . . . . . . . . . . 423
15.165 DWORD (data type) . . . . . . . . . . . . . . . . 424
15.166 ELLIPSE . . . . . . . . . . . . . . . . . . . . . . . 425
15.167 EMPTY TILE . . . . . . . . . . . . . . . . . . . . 426
15.168 EMPTYTILE . . . . . . . . . . . . . . . . . . . . . 427
15.169 ENABLE INTERRUPT . . . . . . . . . . . . . . . 428
15.170 END . . . . . . . . . . . . . . . . . . . . . . . . . 429
15.171 END GAMELOOP . . . . . . . . . . . . . . . . . . 430
15.172 ENDSELECT . . . . . . . . . . . . . . . . . . . . 431
15.173 ENVELOPE . . . . . . . . . . . . . . . . . . . . . 432
15.174 EQUAL (constant) . . . . . . . . . . . . . . . . . . 433
15.175 EVERY OFF . . . . . . . . . . . . . . . . . . . . . 434
15.176 EVERY ON . . . . . . . . . . . . . . . . . . . . . 435
15.177 EVERY...CALL . . . . . . . . . . . . . . . . . . . . 436
15.178 EVERY...GOSUB . . . . . . . . . . . . . . . . . . 438

15
Contents

15.179 EXEC . . . . . . . . . . . . . . . . . . . . . . . . . 440

15.180 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . 441
15.181 EXIT IF . . . . . . . . . . . . . . . . . . . . . . . 442
15.182 EXIT PROC . . . . . . . . . . . . . . . . . . . . . 443
15.183 EXIT PROC IF . . . . . . . . . . . . . . . . . . . . 444
15.184 EXIT PROC WITH...IF . . . . . . . . . . . . . . . 445
15.185 EXIT PROCEDURE . . . . . . . . . . . . . . . . . 446
15.186 EXIT PROCEDURE IF . . . . . . . . . . . . . . . 447
15.187 EXIT PROCEDURE WITH...IF . . . . . . . . . . . 448
15.188 EXP . . . . . . . . . . . . . . . . . . . . . . . . . 449
15.189 FALSE (constant) . . . . . . . . . . . . . . . . . . 450
15.190 FILE (storage) . . . . . . . . . . . . . . . . . . . . 451
15.191 FILL (array) . . . . . . . . . . . . . . . . . . . . . 452
15.192 FILL (instruction) . . . . . . . . . . . . . . . . . . 453
15.193 FIND PORT . . . . . . . . . . . . . . . . . . . . . 454
15.194 FIRE (constant) . . . . . . . . . . . . . . . . . . . 455
15.195 FIRE (function) . . . . . . . . . . . . . . . . . . . 456
15.196 FLIP (function) . . . . . . . . . . . . . . . . . . . 457
15.197 FLIP IMAGE . . . . . . . . . . . . . . . . . . . . . 458
15.198 FLOAT (data type) . . . . . . . . . . . . . . . . . 460
15.199 FONT HEIGHT (constant) . . . . . . . . . . . . . 461
15.200 FONT LOAD . . . . . . . . . . . . . . . . . . . . 462
15.201 FONT WIDTH (constant) . . . . . . . . . . . . . . 463
15.202 FOR...NEXT . . . . . . . . . . . . . . . . . . . . . 464
15.203 FORBID . . . . . . . . . . . . . . . . . . . . . . . 466
15.204 FRAME . . . . . . . . . . . . . . . . . . . . . . . 467
15.205 FRAMES . . . . . . . . . . . . . . . . . . . . . . . 468
15.206 FRAMES COUNT . . . . . . . . . . . . . . . . . . 469
15.207 FREE . . . . . . . . . . . . . . . . . . . . . . . . . 470
15.208 GET . . . . . . . . . . . . . . . . . . . . . . . . . 471
15.209 GET BITMAP . . . . . . . . . . . . . . . . . . . . 472
15.210 GET IMAGE . . . . . . . . . . . . . . . . . . . . . 473
15.211 GET MESSAGE . . . . . . . . . . . . . . . . . . . 474
15.212 GLOBAL . . . . . . . . . . . . . . . . . . . . . . . 475
15.213 GLOBAL CONST . . . . . . . . . . . . . . . . . . 477

16
 Contents

15.214 GOLD (constant) . . . . . . . . . . . . . . . . . . 478

15.215 GOSUB . . . . . . . . . . . . . . . . . . . . . . . 479
15.216 GOTO . . . . . . . . . . . . . . . . . . . . . . . . 481
15.217 GR LOCATE . . . . . . . . . . . . . . . . . . . . . 483
15.218 GRAPHIC . . . . . . . . . . . . . . . . . . . . . . 484
15.219 GRAY (constant) . . . . . . . . . . . . . . . . . . 485
15.220 GREEN (constant) . . . . . . . . . . . . . . . . . . 486
15.221 GREY (constant) . . . . . . . . . . . . . . . . . . 487
15.222 HALT . . . . . . . . . . . . . . . . . . . . . . . . . 488
15.223 HAS BIT . . . . . . . . . . . . . . . . . . . . . . . 489
15.224 HAS NOT BIT . . . . . . . . . . . . . . . . . . . . 490
15.225 HEIGHT (constant) . . . . . . . . . . . . . . . . . 491
15.226 HEX . . . . . . . . . . . . . . . . . . . . . . . . . 492
15.227 HIRES . . . . . . . . . . . . . . . . . . . . . . . . 493
15.228 HIT . . . . . . . . . . . . . . . . . . . . . . . . . . 494
15.229 HOME (constant) . . . . . . . . . . . . . . . . . . 495
15.230 HOME (instruction) . . . . . . . . . . . . . . . . . 496
15.231 HSCROLL . . . . . . . . . . . . . . . . . . . . . . 497
15.232 IF (function) . . . . . . . . . . . . . . . . . . . . . 498
15.233 IF...THEN...ELSE...ELSEIF...ENDIF . . . . . . . . 499
15.234 IMAGE (data type) . . . . . . . . . . . . . . . . . 501
15.235 IMAGE (function) . . . . . . . . . . . . . . . . . . 502
15.236 IMAGE (storage) . . . . . . . . . . . . . . . . . . . 503
15.237 IMAGE HEIGHT . . . . . . . . . . . . . . . . . . . 504
15.238 IMAGE LOAD . . . . . . . . . . . . . . . . . . . . 505
15.239 IMAGE WIDTH . . . . . . . . . . . . . . . . . . . 506
15.240 IMAGES (data type) . . . . . . . . . . . . . . . . . 507
15.241 IMAGES (storage) . . . . . . . . . . . . . . . . . . 508
15.242 IMAGES COUNT . . . . . . . . . . . . . . . . . . 509
15.243 IMAGES LOAD . . . . . . . . . . . . . . . . . . . 510
15.244 IN . . . . . . . . . . . . . . . . . . . . . . . . . . 511
15.245 INC . . . . . . . . . . . . . . . . . . . . . . . . . . 512
15.246 INCLUDE . . . . . . . . . . . . . . . . . . . . . . 513
15.247 INK . . . . . . . . . . . . . . . . . . . . . . . . . . 514
15.248 INKEY . . . . . . . . . . . . . . . . . . . . . . . . 515

17
Contents

15.249 INPUT (function) . . . . . . . . . . . . . . . . . . 516

15.250 INSERT (constant) . . . . . . . . . . . . . . . . . 518
15.251 INSERT (function) . . . . . . . . . . . . . . . . . 519
15.252 INSERT (instruction) . . . . . . . . . . . . . . . . 520
15.253 INST . . . . . . . . . . . . . . . . . . . . . . . . . 521
15.254 INSTR . . . . . . . . . . . . . . . . . . . . . . . . 522
15.255 INSTRUMENT . . . . . . . . . . . . . . . . . . . 523
15.256 INT (data type) . . . . . . . . . . . . . . . . . . . 524
15.257 INT (function) . . . . . . . . . . . . . . . . . . . . 525
15.258 INTEGER (data type) . . . . . . . . . . . . . . . . 526
15.259 IS . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
15.260 IS NOT . . . . . . . . . . . . . . . . . . . . . . . . 528
15.261 JDOWN . . . . . . . . . . . . . . . . . . . . . . . 529
15.262 JFIRE . . . . . . . . . . . . . . . . . . . . . . . . 530
15.263 JLEFT . . . . . . . . . . . . . . . . . . . . . . . . 531
15.264 JOY . . . . . . . . . . . . . . . . . . . . . . . . . 532
15.265 JOY COUNT (constant) . . . . . . . . . . . . . . 533
15.266 JOY DOWN (constant) . . . . . . . . . . . . . . . 534
15.267 JOY FIRE (constant) . . . . . . . . . . . . . . . . 535
15.268 JOY LEFT (constant) . . . . . . . . . . . . . . . . 536
15.269 JOY RIGHT (constant) . . . . . . . . . . . . . . . 537
15.270 JOY UP (constant) . . . . . . . . . . . . . . . . . 538
15.271 JOY X . . . . . . . . . . . . . . . . . . . . . . . . 539
15.272 JOYCOUNT . . . . . . . . . . . . . . . . . . . . . 540
15.273 JOYX . . . . . . . . . . . . . . . . . . . . . . . . . 541
15.274 JOYY . . . . . . . . . . . . . . . . . . . . . . . . . 542
15.275 JRIGHT . . . . . . . . . . . . . . . . . . . . . . . 543
15.276 JUP . . . . . . . . . . . . . . . . . . . . . . . . . 544
15.277 KEY PRESSED . . . . . . . . . . . . . . . . . . . 545
15.278 KEY SHIFT . . . . . . . . . . . . . . . . . . . . . 546
15.279 KEY STATE . . . . . . . . . . . . . . . . . . . . . 548
15.280 KEYGET . . . . . . . . . . . . . . . . . . . . . . . 549
15.281 KEYSHIFT . . . . . . . . . . . . . . . . . . . . . . 550
15.282 KEYSTATE . . . . . . . . . . . . . . . . . . . . . 551
15.283 KILL . . . . . . . . . . . . . . . . . . . . . . . . . 552

18
 Contents

15.284 LAVENDER (constant) . . . . . . . . . . . . . . . 553

15.285 LBOUND . . . . . . . . . . . . . . . . . . . . . . . 554
15.286 LCASE . . . . . . . . . . . . . . . . . . . . . . . . 555
15.287 LEFT (constant) . . . . . . . . . . . . . . . . . . . 556
15.288 LEFT (function) . . . . . . . . . . . . . . . . . . . 557
15.289 LEFT (instruction) . . . . . . . . . . . . . . . . . . 558
15.290 LEFT ALT (constant) . . . . . . . . . . . . . . . . 559
15.291 LEFT ARROW (constant) . . . . . . . . . . . . . . 560
15.292 LEN . . . . . . . . . . . . . . . . . . . . . . . . . 561
15.293 LIGHT BLUE (constant) . . . . . . . . . . . . . . 562
15.294 LIGHT GREEN (constant) . . . . . . . . . . . . . 563
15.295 LIGHT GREY (constant) . . . . . . . . . . . . . . 564
15.296 LIGHT RED (constant) . . . . . . . . . . . . . . . 565
15.297 LINE . . . . . . . . . . . . . . . . . . . . . . . . . 566
15.298 LINE INPUT . . . . . . . . . . . . . . . . . . . . . 567
15.299 LITTLE ENDIAN (constant) . . . . . . . . . . . . 568
15.300 LOAD . . . . . . . . . . . . . . . . . . . . . . . . 570
15.301 LOAD ATLAS . . . . . . . . . . . . . . . . . . . . 571
15.302 LOAD IMAGE . . . . . . . . . . . . . . . . . . . . 574
15.303 LOAD IMAGES . . . . . . . . . . . . . . . . . . . 577
15.304 LOAD MUSIC . . . . . . . . . . . . . . . . . . . . 578
15.305 LOAD SEQUENCE . . . . . . . . . . . . . . . . . 579
15.306 LOAD TILE . . . . . . . . . . . . . . . . . . . . . 582
15.307 LOAD TILEMAP . . . . . . . . . . . . . . . . . . 584
15.308 LOAD TILES . . . . . . . . . . . . . . . . . . . . . 585
15.309 LOAD TILESET . . . . . . . . . . . . . . . . . . . 587
15.310 LOCATE . . . . . . . . . . . . . . . . . . . . . . . 588
15.311 LOCATE (function) . . . . . . . . . . . . . . . . . 590
15.312 LOG . . . . . . . . . . . . . . . . . . . . . . . . . 591
15.313 LOGIN . . . . . . . . . . . . . . . . . . . . . . . . 592
15.314 LONG (data type) . . . . . . . . . . . . . . . . . . 593
15.315 LOOP...END LOOP . . . . . . . . . . . . . . . . . 594
15.316 LOWER . . . . . . . . . . . . . . . . . . . . . . . 595
15.317 MAGENTA (constant) . . . . . . . . . . . . . . . . 596
15.318 MAX . . . . . . . . . . . . . . . . . . . . . . . . . 597

19
Contents

15.319 MEMORIZE . . . . . . . . . . . . . . . . . . . . . 598

15.320 MID (function) . . . . . . . . . . . . . . . . . . . . 599
15.321 MID (instruction) . . . . . . . . . . . . . . . . . . 600
15.322 MIN . . . . . . . . . . . . . . . . . . . . . . . . . 601
15.323 MINUS (constant) . . . . . . . . . . . . . . . . . . 602
15.324 MMOVE . . . . . . . . . . . . . . . . . . . . . . . 603
15.325 MOB OFF . . . . . . . . . . . . . . . . . . . . . . 604
15.326 MOB ON . . . . . . . . . . . . . . . . . . . . . . . 605
15.327 MOD . . . . . . . . . . . . . . . . . . . . . . . . . 606
15.328 MSPRITE (data type) . . . . . . . . . . . . . . . . 608
15.329 MSPRITE (function) . . . . . . . . . . . . . . . . 609
15.330 MSPRITE UPDATE . . . . . . . . . . . . . . . . . 612
15.331 MUL . . . . . . . . . . . . . . . . . . . . . . . . . 613
15.332 MULTI . . . . . . . . . . . . . . . . . . . . . . . . 614
15.333 MULTI OFF . . . . . . . . . . . . . . . . . . . . . 615
15.334 MULTI ON . . . . . . . . . . . . . . . . . . . . . . 616
15.335 MUSIC . . . . . . . . . . . . . . . . . . . . . . . . 617
15.336 MUSIC (data type) . . . . . . . . . . . . . . . . . 619
15.337 MUSIC (storage) . . . . . . . . . . . . . . . . . . . 620
15.338 MUSIC PAUSE . . . . . . . . . . . . . . . . . . . . 621
15.339 MUSIC RESUME . . . . . . . . . . . . . . . . . . 622
15.340 MUSIC SEEK . . . . . . . . . . . . . . . . . . . . 623
15.341 MUSIC STOP . . . . . . . . . . . . . . . . . . . . 624
15.342 NEW ATLAS . . . . . . . . . . . . . . . . . . . . . 625
15.343 NEW IMAGE . . . . . . . . . . . . . . . . . . . . 626
15.344 NEW IMAGES . . . . . . . . . . . . . . . . . . . . 627
15.345 NEW MUSIC . . . . . . . . . . . . . . . . . . . . . 628
15.346 NEW SEQUENCE . . . . . . . . . . . . . . . . . . 629
15.347 NEXT RASTER . . . . . . . . . . . . . . . . . . . 630
15.348 NEXT RASTER AT . . . . . . . . . . . . . . . . . 631
15.349 NONE (constant) . . . . . . . . . . . . . . . . . . 632
15.350 NOP . . . . . . . . . . . . . . . . . . . . . . . . . 633
15.351 NOT . . . . . . . . . . . . . . . . . . . . . . . . . 634
15.352 NOTE (constant) . . . . . . . . . . . . . . . . . . 636
15.353 NRM . . . . . . . . . . . . . . . . . . . . . . . . . 637

20
 Contents

15.354 NTSC (constant) . . . . . . . . . . . . . . . . . . 638

15.355 OLIVE GREEN (constant) . . . . . . . . . . . . . . 639
15.356 ON SCROLL...CALL . . . . . . . . . . . . . . . . . 640
15.357 ON SCROLL...GOSUB . . . . . . . . . . . . . . . 641
15.358 ON...GOSUB . . . . . . . . . . . . . . . . . . . . . 642
15.359 ON...GOTO . . . . . . . . . . . . . . . . . . . . . 643
15.360 ON...PROC . . . . . . . . . . . . . . . . . . . . . 644
15.361 OPTION EXPLICIT . . . . . . . . . . . . . . . . . 645
15.362 OR . . . . . . . . . . . . . . . . . . . . . . . . . . 646
15.363 ORANGE (constant) . . . . . . . . . . . . . . . . . 648
15.364 ORIGIN . . . . . . . . . . . . . . . . . . . . . . . 649
15.365 OUT . . . . . . . . . . . . . . . . . . . . . . . . . 650
15.366 PAGE 0 (constant) . . . . . . . . . . . . . . . . . . 652
15.367 PAGE 1 (constant) . . . . . . . . . . . . . . . . . . 653
15.368 PAGE A (constant) . . . . . . . . . . . . . . . . . 654
15.369 PAINT . . . . . . . . . . . . . . . . . . . . . . . . 655
15.370 PAL (constant) . . . . . . . . . . . . . . . . . . . 656
15.371 PALETTE . . . . . . . . . . . . . . . . . . . . . . 657
15.372 PAPER (function) . . . . . . . . . . . . . . . . . . 658
15.373 PAPER (instruction) . . . . . . . . . . . . . . . . . 659
15.374 PAPER COLORS (constant) . . . . . . . . . . . . 661
15.375 PARAM . . . . . . . . . . . . . . . . . . . . . . . 662
15.376 PCLS . . . . . . . . . . . . . . . . . . . . . . . . . 663
15.377 PEACH (constant) . . . . . . . . . . . . . . . . . . 664
15.378 PEEK . . . . . . . . . . . . . . . . . . . . . . . . 665
15.379 PEEK MESSAGE . . . . . . . . . . . . . . . . . . 666
15.380 PEEKD . . . . . . . . . . . . . . . . . . . . . . . . 667
15.381 PEEKW . . . . . . . . . . . . . . . . . . . . . . . 668
15.382 PEN (function) . . . . . . . . . . . . . . . . . . . 670
15.383 PEN (instrucion) . . . . . . . . . . . . . . . . . . . 671
15.384 PEN COLORS (constant) . . . . . . . . . . . . . . 673
15.385 PERIOD (constant) . . . . . . . . . . . . . . . . . 674
15.386 PI (constant) . . . . . . . . . . . . . . . . . . . . . 675
15.387 PICK . . . . . . . . . . . . . . . . . . . . . . . . . 676
15.388 PING . . . . . . . . . . . . . . . . . . . . . . . . . 677

21
Contents

15.389 PINK (constant) . . . . . . . . . . . . . . . . . . . 678

15.390 PLACE . . . . . . . . . . . . . . . . . . . . . . . . 679
15.391 PLAY (instruction) . . . . . . . . . . . . . . . . . . 680
15.392 PLAY (program) . . . . . . . . . . . . . . . . . . . 681
15.393 PLAY OFF . . . . . . . . . . . . . . . . . . . . . . 682
15.394 PLOT . . . . . . . . . . . . . . . . . . . . . . . . 683
15.395 PLUS (constant) . . . . . . . . . . . . . . . . . . . 685
15.396 PMODE . . . . . . . . . . . . . . . . . . . . . . . 686
15.397 POINT (function) . . . . . . . . . . . . . . . . . . 687
15.398 POINT AT . . . . . . . . . . . . . . . . . . . . . . 688
15.399 POKE . . . . . . . . . . . . . . . . . . . . . . . . 689
15.400 POKED . . . . . . . . . . . . . . . . . . . . . . . 690
15.401 POKEW . . . . . . . . . . . . . . . . . . . . . . . 691
15.402 POLYLINE . . . . . . . . . . . . . . . . . . . . . . 692
15.403 POP . . . . . . . . . . . . . . . . . . . . . . . . . 693
15.404 POP PROCEDURE . . . . . . . . . . . . . . . . . 694
15.405 POSITION (data type) . . . . . . . . . . . . . . . 695
15.406 POUND (constant) . . . . . . . . . . . . . . . . . 696
15.407 POW . . . . . . . . . . . . . . . . . . . . . . . . . 697
15.408 PRINT . . . . . . . . . . . . . . . . . . . . . . . . 698
15.409 PRINT BUFFER . . . . . . . . . . . . . . . . . . . 700
15.410 PROC . . . . . . . . . . . . . . . . . . . . . . . . 701
15.411 PROCEDURE...END PROC . . . . . . . . . . . . . 702
15.412 PURPLE (constant) . . . . . . . . . . . . . . . . . 704
15.413 PUT BITMAP . . . . . . . . . . . . . . . . . . . . 705
15.414 PUT IMAGE . . . . . . . . . . . . . . . . . . . . . 706
15.415 PUT KEY . . . . . . . . . . . . . . . . . . . . . . 708
15.416 PUT MESSAGE . . . . . . . . . . . . . . . . . . . 709
15.417 PUT TILE . . . . . . . . . . . . . . . . . . . . . . 710
15.418 PUT TILEMAP . . . . . . . . . . . . . . . . . . . 711
15.419 RADIAN . . . . . . . . . . . . . . . . . . . . . . . 712
15.420 RANDOM . . . . . . . . . . . . . . . . . . . . . . 713
15.421 RANDOM HEIGHT . . . . . . . . . . . . . . . . . 714
15.422 RANDOM WIDTH . . . . . . . . . . . . . . . . . 715
15.423 RANDOMIZE . . . . . . . . . . . . . . . . . . . . 716

22
 Contents

15.424 RASTER AT . . . . . . . . . . . . . . . . . . . . . 717

15.425 RASTER LINE . . . . . . . . . . . . . . . . . . . . 719
15.426 READ . . . . . . . . . . . . . . . . . . . . . . . . 721
15.427 READ END . . . . . . . . . . . . . . . . . . . . . 722
15.428 READY . . . . . . . . . . . . . . . . . . . . . . . . 723
15.429 REC . . . . . . . . . . . . . . . . . . . . . . . . . 724
15.430 RECEIVE . . . . . . . . . . . . . . . . . . . . . . . 725
15.431 RED (constant) . . . . . . . . . . . . . . . . . . . 726
15.432 REM . . . . . . . . . . . . . . . . . . . . . . . . . 727
15.433 REMEMBER . . . . . . . . . . . . . . . . . . . . . 729
15.434 REPEAT...UNTIL . . . . . . . . . . . . . . . . . . 730
15.435 RESOLUTION . . . . . . . . . . . . . . . . . . . . 731
15.436 RESPAWN (function) . . . . . . . . . . . . . . . . 732
15.437 RESPAWN (instruction) . . . . . . . . . . . . . . . 733
15.438 RESTORE . . . . . . . . . . . . . . . . . . . . . . 734
15.439 RETURN (constant) . . . . . . . . . . . . . . . . . 735
15.440 RETURN (instruction) . . . . . . . . . . . . . . . . 736
15.441 RETURN (procedure) . . . . . . . . . . . . . . . . 737
15.442 RGB . . . . . . . . . . . . . . . . . . . . . . . . . 738
15.443 RIGHT (constant) . . . . . . . . . . . . . . . . . . 739
15.444 RIGHT (function) . . . . . . . . . . . . . . . . . . 740
15.445 RIGHT (instruction) . . . . . . . . . . . . . . . . . 741
15.446 RIGHT ALT (constant) . . . . . . . . . . . . . . . 742
15.447 RIGHT SHIFT (constant) . . . . . . . . . . . . . . 743
15.448 RND . . . . . . . . . . . . . . . . . . . . . . . . . 744
15.449 RND(0) . . . . . . . . . . . . . . . . . . . . . . . 745
15.450 RND(1) . . . . . . . . . . . . . . . . . . . . . . . 746
15.451 ROT . . . . . . . . . . . . . . . . . . . . . . . . . 747
15.452 ROWS (constant) . . . . . . . . . . . . . . . . . . 748
15.453 RUN . . . . . . . . . . . . . . . . . . . . . . . . . 749
15.454 RUN PARALLEL . . . . . . . . . . . . . . . . . . . 750
15.455 RUN STOP (constant) . . . . . . . . . . . . . . . 751
15.456 RUNSTOP (constant) . . . . . . . . . . . . . . . . 752
15.457 SCANCODE . . . . . . . . . . . . . . . . . . . . . 753
15.458 SCREEN (constant) . . . . . . . . . . . . . . . . . 754

23
Contents

15.459 SCREEN (instruction) . . . . . . . . . . . . . . . . 755

15.460 SCREEN BORDER X (constant) . . . . . . . . . . 756
15.461 SCREEN BORDER Y (constant) . . . . . . . . . . 757
15.462 SCREEN COLORS (constant) . . . . . . . . . . . . 758
15.463 SCREEN COLOURS (constant) . . . . . . . . . . . 759
15.464 SCREEN COLUMNS (constant) . . . . . . . . . . 760
15.465 SCREEN COLUMNS (instruction) . . . . . . . . . 761
15.466 SCREEN COLUMNS (instructions) . . . . . . . . . 762
15.467 SCREEN HEIGHT (constant) . . . . . . . . . . . . 763
15.468 SCREEN HORIZONTAL SCROLL . . . . . . . . . 764
15.469 SCREEN OFF . . . . . . . . . . . . . . . . . . . . 765
15.470 SCREEN ON . . . . . . . . . . . . . . . . . . . . . 766
15.471 SCREEN PAGE . . . . . . . . . . . . . . . . . . . 767
15.472 SCREEN ROWS (constant) . . . . . . . . . . . . . 768
15.473 SCREEN ROWS (instruction) . . . . . . . . . . . . 769
15.474 SCREEN SHADES (constant) . . . . . . . . . . . . 770
15.475 SCREEN SPRITE RATIO X (constant) . . . . . . . 771
15.476 SCREEN SPRITE RATIO Y (constant) . . . . . . . 772
15.477 SCREEN SWAP . . . . . . . . . . . . . . . . . . . 773
15.478 SCREEN TILES HEIGHT (constant) . . . . . . . . 774
15.479 SCREEN TILES WIDTH (constant) . . . . . . . . 775
15.480 SCREEN VERTICAL SCROLL . . . . . . . . . . . 776
15.481 SCREEN WIDTH (constant) . . . . . . . . . . . . 777
15.482 SELECT CASE...CASE...CASE ELSE...ENDSELECT 778
15.483 SEND . . . . . . . . . . . . . . . . . . . . . . . . 780
15.484 SEQUENCE (data type) . . . . . . . . . . . . . . . 781
15.485 SET LINE . . . . . . . . . . . . . . . . . . . . . . 782
15.486 SET TAB . . . . . . . . . . . . . . . . . . . . . . 783
15.487 SGN . . . . . . . . . . . . . . . . . . . . . . . . . 784
15.488 SHADES (constant) . . . . . . . . . . . . . . . . . 785
15.489 SHARED . . . . . . . . . . . . . . . . . . . . . . . 786
15.490 SHARED CONST . . . . . . . . . . . . . . . . . . 787
15.491 SHIFT RIGHT (constant) . . . . . . . . . . . . . . 788
15.492 SHOOT . . . . . . . . . . . . . . . . . . . . . . . 789
15.493 SIGNED BYTE (data type) . . . . . . . . . . . . . 790

24
 Contents

15.494 SIGNED DWORD (data type) . . . . . . . . . . . 791

15.495 SIGNED WORD (data type) . . . . . . . . . . . . 792
15.496 SIN . . . . . . . . . . . . . . . . . . . . . . . . . . 793
15.497 SIZE . . . . . . . . . . . . . . . . . . . . . . . . . 794
15.498 SLASH (constant) . . . . . . . . . . . . . . . . . . 795
15.499 SOUND . . . . . . . . . . . . . . . . . . . . . . . 796
15.500 SOUND OFF . . . . . . . . . . . . . . . . . . . . . 797
15.501 SPACE (constant) . . . . . . . . . . . . . . . . . . 798
15.502 SPACE (function) . . . . . . . . . . . . . . . . . . 799
15.503 SPAWN . . . . . . . . . . . . . . . . . . . . . . . 800
15.504 SPC . . . . . . . . . . . . . . . . . . . . . . . . . 801
15.505 SPRITE (data type) . . . . . . . . . . . . . . . . . 802
15.506 SPRITE (function) . . . . . . . . . . . . . . . . . . 803
15.507 SPRITE (instruction) . . . . . . . . . . . . . . . . 805
15.508 SPRITE AT (command) . . . . . . . . . . . . . . . 806
15.509 SPRITE COLOR (command) . . . . . . . . . . . . 808
15.510 SPRITE COMPRESS HORIZONTAL (command) . 809
15.511 SPRITE COMPRESS VERTICAL (command) . . . 810
15.512 SPRITE COUNT (constant) . . . . . . . . . . . . . 811
15.513 SPRITE DISABLE (command) . . . . . . . . . . . 812
15.514 SPRITE ENABLE (command) . . . . . . . . . . . 813
15.515 SPRITE EXPAND HORIZONTAL (command) . . . 814
15.516 SPRITE EXPAND VERTICAL (command) . . . . . 815
15.517 SPRITE HEIGHT (constant) . . . . . . . . . . . . 816
15.518 SPRITE MAX X (constant) . . . . . . . . . . . . . 817
15.519 SPRITE MAX Y (constant) . . . . . . . . . . . . . 818
15.520 SPRITE MIN X (constant) . . . . . . . . . . . . . 819
15.521 SPRITE MIN Y (constant) . . . . . . . . . . . . . 820
15.522 SPRITE MONOCOLOR (command) . . . . . . . . 821
15.523 SPRITE MULTICOLOR (command) . . . . . . . . 822
15.524 SPRITE OFF (command) . . . . . . . . . . . . . . 823
15.525 SPRITE ON (command) . . . . . . . . . . . . . . 824
15.526 SPRITE WIDTH (constant) . . . . . . . . . . . . . 825
15.527 SPRITE X MAX (constant) . . . . . . . . . . . . . 826
15.528 SPRITE X MIN (constant) . . . . . . . . . . . . . 827

25
Contents

15.529 SPRITE Y MAX (constant) . . . . . . . . . . . . . 828

15.530 SPRITE Y MIN (constant) . . . . . . . . . . . . . 829
15.531 SQR . . . . . . . . . . . . . . . . . . . . . . . . . 830
15.532 STORAGE...ENDSTORAGE . . . . . . . . . . . . 831
15.533 STR . . . . . . . . . . . . . . . . . . . . . . . . . 832
15.534 STRING (data type) . . . . . . . . . . . . . . . . . 833
15.535 STRING (function) . . . . . . . . . . . . . . . . . 834
15.536 STRIP (storage) . . . . . . . . . . . . . . . . . . . 835
15.537 STRIP LOAD . . . . . . . . . . . . . . . . . . . . 836
15.538 STRPTR . . . . . . . . . . . . . . . . . . . . . . . 837
15.539 SUCCESS . . . . . . . . . . . . . . . . . . . . . . 838
15.540 SWAP . . . . . . . . . . . . . . . . . . . . . . . . 839
15.541 SYS . . . . . . . . . . . . . . . . . . . . . . . . . 840
15.542 TAB (constant) . . . . . . . . . . . . . . . . . . . 841
15.543 TAB$ . . . . . . . . . . . . . . . . . . . . . . . . . 842
15.544 TAN (constant) . . . . . . . . . . . . . . . . . . . 843
15.545 TAN (function) . . . . . . . . . . . . . . . . . . . 844
15.546 TASK (data type) . . . . . . . . . . . . . . . . . . 845
15.547 TEXT . . . . . . . . . . . . . . . . . . . . . . . . 846
15.548 TEXTADDRESS . . . . . . . . . . . . . . . . . . . 847
15.549 TEXTMAP AT . . . . . . . . . . . . . . . . . . . . 848
15.550 THREAD (data type) . . . . . . . . . . . . . . . . 849
15.551 TI . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
15.552 TICK PER SECOND . . . . . . . . . . . . . . . . 851
15.553 TICKS PER SECOND . . . . . . . . . . . . . . . . 852
15.554 TILE AT . . . . . . . . . . . . . . . . . . . . . . . 853
15.555 TILE BELONG TO . . . . . . . . . . . . . . . . . 854
15.556 TILE CLASS . . . . . . . . . . . . . . . . . . . . . 855
15.557 TILE FIRST . . . . . . . . . . . . . . . . . . . . . 856
15.558 TILE HEIGHT . . . . . . . . . . . . . . . . . . . . 857
15.559 TILE ID . . . . . . . . . . . . . . . . . . . . . . . 858
15.560 TILE LOAD . . . . . . . . . . . . . . . . . . . . . 859
15.561 TILE PROBABILITY . . . . . . . . . . . . . . . . 860
15.562 TILE WIDTH . . . . . . . . . . . . . . . . . . . . 861
15.563 TILEMAP (constant) . . . . . . . . . . . . . . . . 862

26
 Contents

15.564 TILEMAP (storage) . . . . . . . . . . . . . . . . . 863

15.565 TILEMAP AT . . . . . . . . . . . . . . . . . . . . 864
15.566 TILEMAP DISABLE . . . . . . . . . . . . . . . . . 865
15.567 TILEMAP ENABLE . . . . . . . . . . . . . . . . . 866
15.568 TILEMAP HEIGHT . . . . . . . . . . . . . . . . . 867
15.569 TILEMAP INDEX . . . . . . . . . . . . . . . . . . 868
15.570 TILEMAP TILE AT . . . . . . . . . . . . . . . . . 869
15.571 TILEMAP WIDTH . . . . . . . . . . . . . . . . . . 870
15.572 TILES AT . . . . . . . . . . . . . . . . . . . . . . 871
15.573 TILES HEIGHT (constant) . . . . . . . . . . . . . 872
15.574 TILES LOAD . . . . . . . . . . . . . . . . . . . . . 873
15.575 TILES WIDTH (constant) . . . . . . . . . . . . . . 874
15.576 TILESET (storage) . . . . . . . . . . . . . . . . . 875
15.577 TILESET OF . . . . . . . . . . . . . . . . . . . . . 876
15.578 TIMER . . . . . . . . . . . . . . . . . . . . . . . . 877
15.579 TURQUOISE (constant) . . . . . . . . . . . . . . . 878
15.580 UBOUND . . . . . . . . . . . . . . . . . . . . . . 879
15.581 UCASE . . . . . . . . . . . . . . . . . . . . . . . . 880
15.582 UP (constant) . . . . . . . . . . . . . . . . . . . . 881
15.583 UP ARROW (constant) . . . . . . . . . . . . . . . 882
15.584 UPPER . . . . . . . . . . . . . . . . . . . . . . . . 883
15.585 USE TILESET . . . . . . . . . . . . . . . . . . . . 884
15.586 VAL . . . . . . . . . . . . . . . . . . . . . . . . . 885
15.587 VAR . . . . . . . . . . . . . . . . . . . . . . . . . 886
15.588 VARBANK . . . . . . . . . . . . . . . . . . . . . . 887
15.589 VARBANKPTR . . . . . . . . . . . . . . . . . . . 888
15.590 VARPTR . . . . . . . . . . . . . . . . . . . . . . . 889
15.591 VIOLET (constant) . . . . . . . . . . . . . . . . . 890
15.592 VOLUME . . . . . . . . . . . . . . . . . . . . . . . 891
15.593 VOLUME MAX . . . . . . . . . . . . . . . . . . . 892
15.594 VOLUME MIN . . . . . . . . . . . . . . . . . . . . 893
15.595 VOLUME OFF . . . . . . . . . . . . . . . . . . . . 894
15.596 WAIT . . . . . . . . . . . . . . . . . . . . . . . . . 895
15.597 WAIT FIRE . . . . . . . . . . . . . . . . . . . . . 896
15.598 WAIT KEY . . . . . . . . . . . . . . . . . . . . . . 897

27
Contents

15.599 WAIT KEY OR FIRE . . . . . . . . . . . . . . . . 898

15.600 WAIT PARALLEL . . . . . . . . . . . . . . . . . . 899
15.601 WAIT UNTIL . . . . . . . . . . . . . . . . . . . . 900
15.602 WAIT VBL . . . . . . . . . . . . . . . . . . . . . . 901
15.603 WAIT WHILE . . . . . . . . . . . . . . . . . . . . 902
15.604 WHILE...WEND . . . . . . . . . . . . . . . . . . . 903
15.605 WHITE (constant) . . . . . . . . . . . . . . . . . . 904
15.606 WIDTH (constant) . . . . . . . . . . . . . . . . . 905
15.607 WORD (data type) . . . . . . . . . . . . . . . . . 906
15.608 X CURS . . . . . . . . . . . . . . . . . . . . . . . 907
15.609 X GRAPHIC . . . . . . . . . . . . . . . . . . . . . 908
15.610 X TEXT . . . . . . . . . . . . . . . . . . . . . . . 909
15.611 XCURS . . . . . . . . . . . . . . . . . . . . . . . . 910
15.612 XGR . . . . . . . . . . . . . . . . . . . . . . . . . 911
15.613 XGRAPHIC . . . . . . . . . . . . . . . . . . . . . 912
15.614 XOR . . . . . . . . . . . . . . . . . . . . . . . . . 913
15.615 XPEN . . . . . . . . . . . . . . . . . . . . . . . . 915
15.616 XTEXT . . . . . . . . . . . . . . . . . . . . . . . . 916
15.617 Y CURS . . . . . . . . . . . . . . . . . . . . . . . 917
15.618 Y GRAPHIC . . . . . . . . . . . . . . . . . . . . . 918
15.619 Y TEXT . . . . . . . . . . . . . . . . . . . . . . . 919
15.620 YCURS . . . . . . . . . . . . . . . . . . . . . . . . 920
15.621 YELLOW (constant) . . . . . . . . . . . . . . . . . 921
15.622 YELLOW GREEN (constant) . . . . . . . . . . . . 922
15.623 YGR . . . . . . . . . . . . . . . . . . . . . . . . . 923
15.624 YGRAPHIC . . . . . . . . . . . . . . . . . . . . . 924
15.625 YIELD . . . . . . . . . . . . . . . . . . . . . . . . 925
15.626 YPEN . . . . . . . . . . . . . . . . . . . . . . . . 926
15.627 YTEXT . . . . . . . . . . . . . . . . . . . . . . . . 927

16 Advanced topics 929

16.1 Resources and targets . . . . . . . . . . . . . . . . 929
16.2 Game loop . . . . . . . . . . . . . . . . . . . . . . 930
16.3 Using TILED . . . . . . . . . . . . . . . . . . . . . 931
16.3.1 Introduction . . . . . . . . . . . . . . . . . . . 931

28
 Contents

16.3.2 Basic concept: TILESETs . . . . . . . . . . . . 932

16.3.3 Just a single TILE . . . . . . . . . . . . . . . . 933
16.3.4 Basic concept: TILEMAPs . . . . . . . . . . . 934
16.4 Retro (compatible) hacks . . . . . . . . . . . . . . 935
16.5 Endianess . . . . . . . . . . . . . . . . . . . . . . . 936
16.6 Directives (or ”pragma”) . . . . . . . . . . . . . . 937
16.6.1 Language directives . . . . . . . . . . . . . . . 938
OPTION TYPE WIDE/NARROW . . . . . . . 938
OPTION TYPE SIGNED/UNSIGNED . . . . . 939
OPTION EXPLICIT OFF/ON . . . . . . . . . 939
OPTION READ SAFE/FAST . . . . . . . . . . 940
OPTION CLIP ON/OFF . . . . . . . . . . . . 940
OPTION CALL AS GOSUB/GOTO . . . . . . 940
OPTION EXEC AS GOSUB/GOTO . . . . . . 940
OPTION DIALECT dialect . . . . . . . . . . . 941
OPTION DEFAULT TYPE type . . . . . . . . 941
16.6.2 Feature directives . . . . . . . . . . . . . . . . 941
DEFINE AUDIO SYNC/ASYNC . . . . . . . . 942
DEFINE AUDIO TARGET device . . . . . . . . 942
DEFINE CENTER WITH/WITHOUT NEWLINE 943
DEFINE CLS EXPLICIT/IMPLICIT . . . . . . 943
DEFINE COLOR EXPLICIT/IMPLICIT . . . . 943
DEFINE DOUBLE BUFFER OFF/ON . . . . . 943
DEFINE COMPRESSION RLE OFF/ON . . . . 944
DEFINE FLOAT PRECISION precision . . . . . 944
DEFINE FONT schema . . . . . . . . . . . . . 944
DEFINE LOAD BANKED OFF/ON . . . . . . 945
DEFINE INPUT SIZE size . . . . . . . . . . . 945
DEFINE INPUT SEPARATOR char . . . . . . 945
DEFINE INPUT CURSOR char . . . . . . . . . 946
DEFINE INPUT/KEYBOARD RATE value . . 946
DEFINE INPUT/KEYBOARD RATE milliseconds
MS . . . . . . . . . . . . . . . . . . 946
DEFINE INPUT/KEYBOARD DELAY value . . 946

29
Contents

DEFINE INPUT/KEYBOARD DELAY millisec-

onds MS . . . . . . . . . . . . . . . 946
DEFINE JOYSTICK RETRIES number . . . . . 946
DEFINE JOYSTICK SYNC/ASYNC . . . . . . 947
DEFINE KEY PRESS SYNC/ASYNC . . . . . 947
DEFINE KEYBOARD SYNC/ASYNC . . . . . 947
DEFINE MSPRITE SYNC/ASYNC . . . . . . . 947
DEFINE PALETTE [NOT] PRESERVE . . . . 948
DEFINE PROGRAM START address . . . . . 948
DEFINE PAINT BUFFER size . . . . . . . . . 949
DEFINE SCREEN MODE UNIQUE . . . . . . 950
DEFINE STRING COUNT number . . . . . . . 950
DEFINE STRING SPACE size . . . . . . . . . 950
DEFINE TASK COUNT number . . . . . . . . 950
16.6.3 Hardware directives . . . . . . . . . . . . . . . 950
CONFIGURE GMC SLOT number . . . . . . . 951
CONFIGURE SN76489 ADDRESS address . . . 951

30
1 Introduction

1.1 Welcome!

Are you fascinated by the world of programming but feel overwhelmed

by modern languages? Have you ever dreamed of reliving the magic
of the first home computers? Of creating your own video games or
exploring virtual worlds limited only by your imagination? Are you ready
to get your hands dirty and write your first program?

With ugBASIC, a language inspired by the classic BASIC of the 80s,

you can create software for a wide range of retrocomputers. With a
simple and intuitive syntax, this language will guide you step by step
through the fundamentals of programming. You will learn how to write
algorithms, manage variables, create data structures and much more.

With the ability to natively handle graphic and sound formats, your
creativity will have no limits. Whether you want to create an exciting
game, a colorful animation or a simple utility, this language will provide
you with all the tools you need.
The advantage of writing with ugBasic is related to the time/result
ratio, which is high. Writing a program in assembly is a very long task,
but with ugBASIC it becomes a matter of little time.
For example, ugBASIC loads and draws an image with a single com-
mand, adapts the formats of the image itself and calibrates the computer
palette very precisely directly from the colors of the image.

31
1 Introduction

The work savings are such that it allows you to create high-performance
games in a short time, and it opens the way to programmers who would
like to write something for retro machines but are often discouraged by
the slowness of BASIC, or by the disadvantages of assembly.

Discover how to give new life to these legendary machines and rediscover
the pure pleasure of programming, get ready to build a solid foundation
to tackle more complex languages!
This book will guide you through a practical and engaging journey.
You will learn how to install ugBASIC, write your first code, and solve
common problems. With numerous examples, you will acquire the skills
necessary to become an expert ugBASIC programmer.
If you need help, there is the official forum, where you can ask questions
and receive answers:
https://forum.ugbasic.iwashere.eu/

1.2 Features

In this section, below, there are the most interesting features if you use
ugBASIC as the main programming language:

• Rapid development - ugBASIC is able to handle graphics with

double buffering (if hardware is able to), to use directly PNG/JPG
and other standard image formats, to manage additional RAM
banks, to read multiple keyboard keys at the same time and to
do inline assembly.

• Fast animations - ugBASIC can do real-time animation of fairly

large sprites. Sprites can also move in a full background setting.
This new language will allow for hyper-fast game development on
all 8-bit consoles and computers.
• Fast drawing - the characteristics of the language are such as to

32
 1.3 Games

allow fast execution of the same BASIC source on various home

computers and consoles, such vector graphics render.
• Console support - full and complete support for console hardware
features on ColecoVision, SEGA SC-3000 and SEGA SG-1000.
Automatic graphic conversion from modern graphical formats in-
cluded.
• Strong optimizations - each target can have a dedicated con-
textual and peephole optimizer, which allows to achieve very in-
teresting results while leaving the BASIC code fully readable.

• Native multitasking - it is simple to write multitasking programs

using parallel programming, available ”out of the box” in ugBA-
SIC.

1.3 Games

Some games made with ugBASIC (in no particular order). A more

complete list, with the level of compatibility with all platforms supported
by ugBASIC, can be read here:
https://ugbasic.iwashere.eu/games

• Creepy Carrots by Paolo Cattaneo - it is a clone of Manic Miner,

where you have to collect all the carrots and reach the exit of the
level. The game shows the capabilities of ugBASIC: graphics in
160x200x16, switching video pages, managing 3 banks of RAM
in addition to the main memory, reading multiple keyboard keys
at the same time (if hardware allows it), and inline ASM.

More at:
https://github.com/cttpla/Creepy-Carrots

33
1 Introduction

• The Savage Sword of COCON by Erico Patricio Monteiro - it is

brawler on the lines of Barbarian. It runs on a TRS-80 Color Com-
puter with 64kb, requires a disk drive and at least one joystick.
It can be single played against the 5 kingdom’s sword masters, vs
played against a friend and also vs played by RPG stats, where
each player designs a barbarian and you get to watch them go.

More at:
https://sites.google.com/view/fuedhq/cocon

• SOKO64+ by Marco Spedaletti and Emanuele Feronato - it is a

puzzle-type video game in which the player pushes crates through
a maze and tries to place them in their assigned location.

More at:
https://spotlessmind1975.itch.io/soko64plus

• SOKO64 by Emanuele Feronato - it is a famous puzzle game

designed in 1981 by Hiroyuki Imabayashi, and first published in
December 1982. This C64 version includes 64 8x8 tricky levels
by David Skinner.

More at:
https://triqui.itch.io/soko64

• 4GRAVITY! by Marco Spedaletti - it is a ”Connect Four” clone.

The objective of the game is to be the first to form a horizontal,
vertical, or diagonal line of four of one’s own tokens.

More at:
https://spotlessmind1975.itch.io/4gravity

34
 1.4 Beta version

1.4 Beta version

Imagine you have a new video game that you’re developing. Before you
release it to the public, you want other people to try it to find any bugs
or problems. That’s what a beta version is for. So, the beta version
of ugBASIC is a near-complete, but not final, version that is released
for testing. The goal is to find and fix any errors or bugs before the
official release.
The beta version is not the final version of the compiler, and may
contain bugs or run unstable. Users who try the beta version are
called ”beta testers” and provide important feedback.
Beta testers can spot errors and issues that developers may not have
noticed during internal development phases. User feedback can help
improve the user interface and overall experience. Beta testers can
report any performance issues, such as slowdowns or crashes. Finally,
Beta is used to ensure that the software is ready for use by a wider
audience.
Based on feedback from beta testers, the author can make changes
and improvements to the software before the final release. The beta
versions are distributed in a separate branch and distribution mean.

35
1 Introduction

1.5 What is isomorphism?

Everything started a few years ago, when I discovered that I could

program in C on 8-bit computers, specifically the Commodore 64.

It had always been my dream to be able to do it, so I started writing

some games with this language, and a library of common used functions.
Since the C language is by its nature portable, I started to create a library
that would allow the same game to run on different computers, i.e. on
MSX or ZX Spectrum.

Here I ran into a number of limitations of modern languages when

used on 8-bit systems. Wanting to create something portable but, at
the same time, efficient, I invented a new programming paradigm that I
called ”isomorphism”. I introduced this paradigm on this 8-bit C library,
and then I used it as the founding pillar of ugBASIC.
In a nutshell, ”isomorphism” means the attempt to match one part of
one computer to the counterpart part of another computer in the ”best
way”, and for every supported hardware combination. Hence the term
that, in mathematics, is a one-to-one correspondence between two sets.
The goal is to have software written for one computer that can run (with
minimal modifications) on others, and with minimal loss of performance.
This is done basically by not introducing unnecessary abstractions.
To give a concrete example: all computers allow you to print a character
on the screen. The way they do this, however, varies from computer to
computer. The classic solution is to ”abstract” the concept of screen,
assume that it behaves identically everywhere, and then implement it
the same everywhere. The isomorphic approach, on the other hand,
recognizes that functionality could exist in every target but it is probably
differently implemented in every one. Or it might not even exist, and
there might be no point in implementing it.
Another concrete example, this time the opposite. All modern lan-

36
 1.5 What is isomorphism?

guages rely on there being a stack to maintain local variables. In reality,

almost all 8-bit processors do not have efficient stacks. So this abstrac-
tion is no good. For this reason, isomorphism implements a stackless
approach. All memory is statically allocated. In C this was done by
using global variables.
In conclusion: the language will provide the programmer with the con-
ceptual functionality, letting each target implement it as best as possi-
ble. I emphasize here that I used the word ”language”, and not library.
The reason I abandoned C was because with the C library, once the
isomorphic approach was implemented, you no longer programmed in
C. In practice there was no longer a distinction between ”library” and
”language”. So it had no sense to continue to use C.
Having to choose a language, I chose BASIC. For two reasons. The first
is that it was the language of choice for almost all home computers of
the time, which makes it very common and it allows the same algorithms
to be used. The second is that it is a language that makes no distinctions
between ”syntax” and ”libraries”, and is therefore ideal for isomorphism.
To date, ugBASIC generates executables for around twenty targets.
When I say ”target” I don’t simply mean that ugBASIC produces some-
thing for it, but I can say that a program also runs on that target.

Obviously, being an isomorphic language without abstractions, it is not

guaranteed that the result will be the same and the goal is not to make
it run badly just to make it run.
For example, if a target has no bitmap graphics because it only has
text modes, ugBASIC provides no abstractions to solve the problem.
At the same time, however, it can offer very interesting alternatives.
For example, on the VIC-20 it can reprogram characters to mimic the
availability of images, but obviously this is not available on bitmap only
targets.

By taking this approach, you will find that writing cross target sources
in ugBASIC is feasible, and it depends on isomorphism. And, if you

37
1 Introduction

are not interested in portability, the language will be able to provide

satisfaction for the specific target you choose.
Thank you for reading, and happy retrocoding!
Marco Spedaletti

38
2 Getting started
ugBASIC lets you create complex, high-performance programs for retro
computers, using a language that integrates all the advanced features
typical of assembly.
For example, you can effortlessly draw 32 sprites on the VIC-II chipsets,
which is quite an achievement, especially considering that the Com-
modore 64 hardware actually only provides eight.

You can also use images created in any graphics mode you like, if you
want. The only limit is the amount of available memory, which can be
expanded transparently with the use of memory expansions.
ugBASIC supports 669 commands, and if you’ve never used BASIC
before, you might feel a little overwhelmed. It is therefore advisable to
have a guide that shows you a sort of ”map” and indicates some of the
most important reference points.
The purpose of this chapter is to get started.

39
2 Getting started

2.1 Using sandbox

Imagine a sandbox as a small virtual island, completely separate from

your computer. On this island, you can do whatever you want: build
sand castles, dig holes, without worrying about dirtying or damaging
the rest of the garden.
The ugBASIC sandbox works in a very similar way. It is an isolated
and safe environment where you can run code, test new ideas, and
experiment with different sources without risking damage anything.

If you are writing a new program or modifying existing code, and you
have no ugBASIC installed on your syste, you can run it inside the
sandbox to see if it works correctly.
Sandboxes are perfect for beginners who want to practice without hav-
ing to install complicated software or set up development environ-
ments. Infact, the ugBASIC sandbox is accessible through as simple
web browser, so you don’t have to install any software on your com-
puter.
ugBASIC sanbox is here:
https://sandbox.ugbasic.iwashere.eu/

The ugBASIC sandbox is limited: to learn more about ugBASIC’s

capabilities, such as loading images, see the next chapter.

40
 2.2 Install ugBASIC

2.2 Install ugBASIC

The ugBASIC compiler is mainly a console application for Linux and Mi-
crosoft Windows operating system, with a convenient IDE environment
for Microsoft Windows only.
The ugBASIC-IDE offers a more complete and user-friendly develop-
ment environment than the command line one, making programming
more accessible to both beginners and experienced developers. With
the IDE you can edit and compile your ugBASIC sources efficiently and
effectively for multiple retrocomputers, and it makes easier to download
and install the various software required, all just one ”click away”.
We suggest to install the UGBASIC-IDE by visiting this link:
https://spotlessmind1975.itch.io/ugbasic-ide

On the other hand, if you prefer to use the command line version, in-
stalling ugBASIC may vary slightly, depending on your operating system
and target (the type of 8-bit computer you want to create programs for).
The main steps for both are always the same:

1. Choose your target: decide which 8-bit computer you want to

develop your programs for.

2. Download the compiler: on the official ugBASIC website you

will find links to download pre-compiled binaries for different op-
erating systems and targets.
3. Download additional software: download additional software,
specific to the target used, such as assemblers

4. Configure the path: add the path to the folder containing the
compiler to your PATH environment variable. This will allow you
to run the compiler from any directory.
5. Verify the installation: try running the compiler from the com-

41
2 Getting started

mand line. If everything went well, you should see a welcome

message.

There is a web page where you can download the correct compiler for
your specific target, by following a series of simple steps:
https://ugbasic.iwashere.eu/install

2.2.1 Choose your target

Which 8-bit machine do you want to program? The ugBASIC language

supports a wide range of models, from Commodore 64 to Atari to ZX
Spectrum. This is the list of targets that are supported by ugBASIC,
according to the current version (currently: 1.16.4 ):

• atarixl : Atari 1200XL, Atari 130XE, Atari 600XL, Atari 65XE,

Atari 800XE, Atari 800XL, Atari XEGS

• atari : Atari 400, Atari 800

• c128 : Commodore 128 (using the CPU MOS 8502)
• c128z : Commodore 128 (using the CPU Zilog Z80)
• c64 : Commodore 64, Commodore Executive 64

• c64reu : Commodore 64 + REU (Ram Expansion Unit)

• coco : TRS-80 Color Computer, TRS-80 Color Computer 2
• coco3 : TRS-80 Color Computer 3

• coleco : Coleco Vision, Dina (Chuang Zao Zhe 50), Spec-

traVideo SV-603 VGA
• cpc : Amstrad CPC 464, Amstrad CPC 6128, Amstrad CPC 664
• d32 : Dragon 32

42
 2.2 Install ugBASIC

• d64 : Dragon 64
• mo5 : Thomson MO5
• msx1 : MSX

• pc128op : Olivetti Prodest PC128, Thomson MO6

• plus4 : Commodore Plus/4
• sc3000 : SEGA SC-3000

• sg1000 : SEGA SG-1000

• to8 : Thomson TO8
• vic20 : Commodore VIC-20
• zx : ZX Spectrum +2, ZX Spectrum 128K, ZX Spectrum 48K

This list will be updated as the various targets are implemented and
made available:

2.2.2 Download the compiler

Pre-compiled binaries are available for Linux and Windows systems, for
the latest stable version or a for a specific version, if you have special
needs.

The compiler is named ugbc.target on Linux and ugbc.target.exe

on Microsoft Windows, and it can be downloaded directly from the
official page:
https://ugbasic.iwashere.eu/install

43
2 Getting started

2.2.3 Download additional software

Normally, ugBASIC compilers only generate assembly code. However,

it can be useful and convenient to have the executables generated in
a directly usable format. To do this, you need to install a series of
additional software, depending on the target you want to program.

• asm6809 : asm6809 is a portable cross assembler targeting the

Motorola 6809 and Hitachi 6309. Features arbitrarily complex
expressions (with most C-style operators available), forward ref-
erences, macro expansion and conditional assembly. Output for-
mats are: Raw binary, DragonDOS binary, CoCo RS-DOS (or
”DECB”) binary, Motorola SREC, Intel HEX. To install it you
can download the executable from official website:

Link: https://www.6809.org.uk/asm6809/

• cc65 : cc65 is a complete cross development package for 65(C)02

systems, including a powerful macro assembler, a C compiler,
linker, librarian and several other tools. To install it is enough to
require the correct package.

Link: https://cc65.github.io/

• z88dk : z88dk is the only C and assembler development kit that

comes ready out-of-the-box to create programs for over 100 z80-
family (8080, 8085, gbz80, z80, z180, ez80, Rabbit 2000, Rabbit
3000) machines. The project was started in 1998/9 to allow a
TCP stack for the Cambridge z88 to be easily written. In re-
cent years significant work has been undertaken to improve the
number of targets supported, enhance library features, make the

44
 2.2 Install ugBASIC

toolchain easier to. To install it you can download the executable

from official website:

Link: https://z88dk.org/site/

2.2.4 Configure the path

The PATH variable tells the operating system where to look for com-
mands (such as ugBASIC) when you type them at the command prompt.
By setting the PATH correctly, you can run ugBASIC commands from
any directory on your system without having to specify the full path
each time. This greatly simplifies the use of the compiler.

On Microsoft Windows

To change PATH on Microsoft Windows, open ”System Properties”:

• Right-click the ”This PC” (or ”Computer”) icon on the desktop

• Select ”Properties”
• Click ”Advanced System Settings”

In the ”System Propertie”s window, click the ”Environment Variables”

button. In the ”System Variables” section, find the ”Path” variable and
click ”Modify”. Click ”New” and paste the path to the folder containing
the ugBASIC executable (for example, C:\ugbasic\bin). Click ”OK”
to confirm all changes.
Important: It is often necessary to restart the command prompt session
or the computer for changes to take effect.

45
2 Getting started

On Linux

On Linux, the procedure varies slightly depending on the distribution

and the shell used (bash, zsh, etc.). However, the principle is the same:
add the path to the folder containing ugBASIC to the PATH variable.

So open a terminal, then type echo $PATH and press enter. This will
display the list of paths currently included. To add the path to the
ugBASIC folder (for example, /usr/local/bin/ugbasic), type the
following command and press enter:
export PATH=$PATH:/usr/local/bin/ugbasic

To make this change permanent, add the above line to a shell configu-
ration file, such as .bashrc or .zshrc. Open the file with a text editor
(for example, nano /.bashrc) and add the line to the end of the file.
Close and reopen the terminal to apply the changes.

2.2.5 Verify the installation

Verifying that ugBASIC has been installed correctly and is working as

expected is a crucial step in getting started with programming. Here
are some simple ways to do this:

• open a command prompt (Windows) or terminal (Linux)

• type the command for the target you installed, for example: ugbc.c64

If everything is installed correctly, you should see a help message listing

the various commands and options available, as follows:
--------------------------------------------------
ugBASIC Compiler v1 .16.4 [ target : Commodore 64]
--------------------------------------------------
Copyright 2021 -2024 Marco Spedaletti ( asimov@mclink . it )

46
 2.2 Install ugBASIC

If you get an error like ”command not found”, this means that the path
(PATH) has not been configured, or has not been updated. In this case,
you should double-check that the path entered in the PATH variable
during installation is correct.

Finally, you can create a new file using a text editor, a file with the .bas
extension (for example, myprogram.bas). Insert the following code
into the file:
PRINT " Hello , world !"

Come back to the prompt, and type the following command:

ugbc.c64 myprogram.bas myprogram.asm

If everything works correctly, an assembly file will be created for your
target machine. To build and executable, and to check if assemblers
are correctly installed, you can use the following command:

ugbc.c64 -O prg -o myprogram.prg myprogram.bas

If everything works correctly, the program executable will be created.
Run the executable file to see if the ”Hello, world!” message displays
correctly in the emulator and on your real machine.

47
2 Getting started

2.3 Install UGBASIC-IDE

The ugBASIC-IDE offers a more complete and user-friendly develop-

ment environment than the command line one, making programming
more accessible to both beginners and experienced developers. With
the IDE you can edit and compile your ugBASIC sources efficiently and
effectively for multiple retrocomputers, and it makes easier to download
and install the various software required, all just one ”click away”.
We suggest to support and download the UGBASIC-IDE by visiting:

https://spotlessmind1975.itch.io/ugbasic-ide/purchase

The IDE is completely free of charge. If you like it, you can support
new functions and bug correction thanks to a free donation.

48
3 ”BASIC” concepts
ugBASIC is ispired from BASIC (Beginner’s All-purpose Symbolic In-
struction Code), that was one of the first high-level programming lan-
guages, designed to be easy to learn and use, especially for those ap-
proaching programming for the first time.

Infact, it was designed to be easy to understand, even by people with-

out specific computer science training. The syntax is clear and con-
cise, and instructions are often expressed in easily memorable keywords.
Moreover, it supports basic data types such as integers, floating-point
numbers, and text strings. The statements include assigning values to
variables, arithmetic operations, flow control (such as IF, THEN, ELSE,
FOR, NEXT), input/output, and subroutine calls.
So, an ugBASIC program is essentially a sequence of statements. The
program executes sequentially, unless flow control statements alter the
order of execution.

The ugBASIC is a great place to start learning basic programming con-

cepts, such as variables, conditional statements, loops, and functions.
By comparing ugBASIC to modern languages, you can appreciate how
programming languages have evolved over the years.
Moreover, if you’re interested in retrocomputing, ugBASIC is an ideal
language for many 8-bit machines. So, it remains an interesting and
useful programming language for those who want to delve deeper into
the fundamentals of programming. Its simplicity and widespread use
make it a great starting point for anyone who wants to get started in
the world of programming.

49
3 ”BASIC” concepts

3.1 Syntax

3.1.1 Keywords

The language has 669 keywords, that form the entire vocabulary of
the language. The keywords must be written in UPPER case. Therefore
PRINT is a valid command, while print is not. In ugBASIC (like CBM
BASIC) you do not need to isolate keywords from each other or from
other identifiers with any separator, like spaces.

This is the complete list of keywords:

16BIT AAHS ABS ACCORDION ACOUSTIC ADD ADDRESS AFTER AGE AGOGO
ALL ALLOW ALT ALTO AND APPLAUSE ARRAY ARROW AS ASC ASCII
ASCIICODE ASM ASTERISK ASYNC AT ATARI ATARIXL ATLAS ATMOSPHERE
AUDIO AUTO AVAILABLE BACK BACKGROUND BAG BANJO BANK BANKED
BAR BARITONE BASS BASSOON BEG BEGIN BELL BELLS BELONG BETA
BF BIG BIN BINARY BIRD BIT BITMAP BITMAPS BLACK BLIT BLOCK
BLOWN BLUE BOOM BORDER BOTTLE BOWED BOX BRASS BREATH BRIGHT
BRIGHTNESS BROWN BUFFER BUT BYTE CALL CALLIOPE CAN CAPS CAPSLOCK
CASE CDOWN CELESTA CELLO CENTER CENTRE CGOTO CHAR CHARANG
CHECK CHIFF CHOIR CHR CHURCH CIRCLE CLARINET CLASS CLAVI
CLEAN CLEAR CLEFT CLINE CLIP CLS CMOB CMOVE COCO CODE COLECO
COLLISION COLON COLOR COLORMAP COLORS COLOUR COLOURMAP COLOURS
COLUMN COLUMNS COMBINE COMMA COMMODORE COMPLETE COMPRESS
COMPRESSED COMPRESSION CONFIGURE CONSOLE CONST CONTRABASS
CONTROL COPY COS COUNT CPC CREATE CRIGHT CRSR CRYSTAL CSET
CSPRITE CUP CURSOR CYAN CYCLES CYMBAL DARK DATA DEC DECLARE
DEFAULT DEFDGR DEFINE DEGREE DELAY DELETE DESTINATION DESTROY
DETECTION DIALECT DIM DIRECTION DISABLE DISTANCE DISTORTION
DIV DLOAD DO DOJO DOJOKA DOUBLE DOWN DRAGON DRAW DRAWBAR DRUM
DRUMS DSAVE DTILE DTILES DULCIMER DUP DWORD DYNAMIC ECHOES
ELECTRIC ELLIPSE ELSE ELSEIF EMBEDDED EMPTY EMPTYTILE ENABLE
END ENDIAN ENDIF ENDSELECT ENDSTORAGE ENGLISH ENSEMBLE ENVELOPE

50
 3.1 Syntax

EQUAL ERROR EVERY EXACT EXEC EXIT EXP EXPAND EXPLICIT EXPLOSION
FALSE FAST FI FIDDLE FIFTHS FILEX FILL FIND FINGER FIRE FIRST
FLIP FLOAT FLUTE FONT FOR FORBID FRAME FRAMES FREE FRENCH
FRET FRETLESS FROM FUNCTION FX GAMELOOP GET GLOBAL GLOCKENSPIEL
GMC GOBLINS GOLD GOSUB GOTO GR GRAND GRAPHIC GRAY GREEN GREY
GUITAR GUNSHOT HALO HALT HALTED HARMONICA HARMONICS HARP
HARPSICHORD HAS HEIGHT HELICOPTER HEX HIRES HIT HOME HONKY
HORIZONTAL HORN HSCROLL IAF ID IF IGNORE IMAGE IMAGES IMPLICIT
IN INC INDEX INK INKEY INPUT INSERT INST INSTR INSTRUMENT
INT INTEGER INTERRUPT INVERSE IS JAZZ JDOWN JFIRE JLEFT JOY
JOYCOUNT JOYSTICK JOYX JOYY JRIGHT JUP KALIMBA KEY KEYBOARD
KEYGET KEYSHIFT KEYSTATE KILL KOTO LATENCY LAVENDER LAYER
LBOUND LCASE LEAD LEFT LEN LET LIGHT LINE LITTLE LOAD LOCATE
LOCK LOG LOGIN LONG LOOP LOWER MAGENTA MARIMBA MASKED MAX
MELODIC MEMORIZE MEMORY MESSAGE METALLIC MID MIDI MILLISECOND
MILLISECONDS MIN MINUS MMOVE MOB MOD MODE MONOCOLOR MONOCOLOUR
MOVE MSPRITE MSX MUL MULTI MULTICOLOR MULTICOLOUR MUSIC MUTED
NAMED NARROW NEW NEWLINE NEXT NIBBLE NOISE NONE NOP NORMAL
NOT NOTE NRM NTSC NYLON OBOE OCARINA OF OFF OFFSET OLIVE
ON ONLY OOHS OPACITY OPTION OR ORANGE ORCHESTRA ORCHESTRAL
ORGAN ORIGIN OUT OVERDRIVEN OVERLAYED PAD PAGE PAINT PAL
PALETTE PAN PAPER PARALLEL PARAM PAUSE PCLS PEACH PEEKD PEEKW
PEN PER PERCUSSIVE PERIOD PI PIANO PICCOLO PICK PING PINK
PIPE PIZZICATO PLACE PLAY PLOT PLUS PMODE POINT POKED POKEW
POLYLINE POLYSYNTH POP PORT POSITION POSITIVE POUND POWERING
PRECISION PRESERVE PRESET PRESSED PRINT PROBABILITY PROC
PROCEDURE PROGRAM PSET PSG PURPLE PUT RADIAN RAIN RANDOM
RANDOMIZE RASTER RATE RATIO RAW READ READONLY READY REC RECEIVE
RECORDER RED REED RELATIVE RELEASE REMEMBER REPEAT REPLACE
RESIDENT RESOLUTION RESPAWN RESTORE RESUME RETRIES RETURN
REVERSE RGB RIGHT RING RLE RND ROCK ROLL ROT ROW ROWS RUN
RUNSTOP SAFE SAVE SAWTOOTH SAX SCAN SCANCODE SCANSHIFT SCI
SCREEN SCROLL SEASHORE SECOND SECTION SEEK SELECT SEMICOLON
SEMIGRAPHIC SEND SEPARATOR SEQUENCE SET SGN SHADES SHAKUHACHI
SHAMISEN SHANAI SHARED SHIFT SHOOT SIGNED SIN SINGLE SITAR

51
3 ”BASIC” concepts

SIZE SLAP SLASH SLICE SLOT SOPRANO SOUND SOUNDTRACK SOURCE

SPACE SPAWN SPC SPEED SPRITE SQR SQUARE STACK STANDARD START
STATE STATIC STEEL STEP STOP STORAGE STR STRING STRINGS STRIP
STRPTR SUCCESS SWAP SWEEP SYNC SYNTH SYNTHBRASS SYNTHSTRINGS
SYS SYSTEM TAB TAIKO TAN TANGO TARGET TASK TELEPHONE TEMPORARY
TENOR TEXT TEXTADDRESS TEXTMAP THEN THREAD THRESHOLD TI TICK
TICKS TILE TILEMAP TILES TILESET TIME TIMER TIMPANI TINKLE
TO TOM TONK TRANSPARENCY TRANSPARENT TREMOLO TROMBONE TRUE
TRUMPET TSB TUBA TUBULAR TURQUOISE TWEET TYPE UBOUND UCASE
UGBASIC UNBANKED UNIQUE UNSIGNED UNTIL UP UPDATE UPPER USE
VAL VALUE VALUES VAR VARBANK VARBANKPTR VARIABLES VARPTR
VBL VERTICAL VIBRAPHONE VIDEO VIOLA VIOLET VIOLIN VISIBLE
VOICE VOLUME VSCROLL WAIT WARM WAVE WEND WHILE WHISTLE WHITE
WIDE WIDTH WITH WITHOUT WOODBLOCK WORD WRITE WRITING XCURS
XGR XGRAPHIC XOR XPEN XTEXT XY XYLOPHONE YCURS YELLOW YGR
YGRAPHIC YIELD YPEN YTEXT YX ZX

3.1.2 Identifiers

Identifiers are used to give a name to labels, variables, constants, proce-

dures and functions. You may choose any name for identifier. Anyway,
you have to follow some rules:

• the first character must be lowercase alphabetic;

• the remaining characters can be of any case;
• the dollar symbol ($) identify string variables;
• identifier are case sensitive: pippo and pIPPO are different sym-
bols;
• they can be of any length, and all characters are significant.

Here you are some examples:

52
 3.1 Syntax

1 functionName
2 score
3 iAmStillAlive42

3.1.3 Statements

Statements and commands can be separated using the colon symbol

(:) character, and can end with LF (line feed) or CR+LF (carriage
return followed by a line feed) characters. The separator is not required
if there’s only one statement in one line, as the following example:
1 WHILE NOT finished : PRINT " continue " : WEND
2 WHILE NOT finished
3 PRINT " continue "
4 WEND

3.1.4 Split (long) lines

The underscore ( ) character at the end of the line can be used to split
a single line to multiple lines, in order to be more readable.
1 ’ Write this very long line in a short one .
2 DIM xx (32) AS BYTE = # { _
3 x1 , x2 , x3 , x1 , x2 , x3 , x1 , x2 , _
4 x3 , x1 , x2 , x3 , x1 , x2 , x3 , x1 , _
5 x2 , x3 , x1 , x2 , x3 , x1 , x2 , x3 , _
6 x1 , x2 , x3 , x1 , x2 , x3 , x1 , x2 , _
7 }

3.1.5 Comments

Comments have the role to describe the purpose of a particular section

of code or individual statement, and it provide information about the
program, who created it, when it was created, and what changes were
made. They make code easier to understand, even for people who

53
 3 ”BASIC” concepts

did not write the program: when you return to code after some time,
comments help you remember the purpose of different parts of the
program.
Here you are some examples:
1 ’ comment
2 REM comment
3 line = 1 : ’ comment
4 line = 1 : REM comment

If you begin a line with single quote (’) character, or put it after colon
symbol, it will be considered a comment until the end of the line. The
same for the REM command, that is used to begin a comment.
The best way to disable a piece of code without deleting it, simply add
REM to the beginning of the line.

The main guidelines in using REM it to use simple, direct language to

explain the code, avoiding long or complicated sentences. Generally,
they should be used on parts of the code that are not obvious. You do
not need to comment on every single line.

3.1.6 White spaces

White space (e.g. spaces and tabs) are ignored, since they are not
needed. You are encouraged to use them if you need to make make the
program more readable, or to remove it if you need to join competitions
where number of lines is an important factor.
Here you are some examples:
1 ’ With white spaces
2 10 PRINT " HELLO !": GOTO 10
3 ’ Without white spaces
4 10 PRINT " HELLO !": GOTO10

54
 3.1 Syntax

3.1.7 Labels (and line numbers)

Labels can be used to identify any point of the source code. Labels
are used by some statements, like GOTO and GOSUB statements. Labels
must be appended with a colon character (:). As in traditional BASIC
language, labels can be numeric, as well. Line numbers are treated like
special labels by ugBASIC, as they must not followed by colon character
(:).

1 10 PRINT " LOOP !"

2 GOSUB subroutine1
3 GOTO 10
4 subroutine1 :
5 PRINT " subroutine1 has been called !"
6 RETURN

3.1.8 Hash operator

In general, the hash operator (#) allows you to indicate the will to refer,
explicitly, to a constant rather than to a value mediated by a variable.
Without this operator, ugBASIC may decide to make a temporary copy
of the value before using it. This can be inefficient.

1 fontSize = # constantSize
2 fontSize = #42

Therefore it is possible to indicate the will to actually refer to the equiv-

alent value. For this reason, this operator works only if it is used with a
constant value (eg: an integer) or with the name of a constant. How-
ever, it should be noted that this operator is not always available. In
some contexts, such as the definition of constants, its use would be
redundant.

55
 3 ”BASIC” concepts

3.1.9 Buffer definition

The ugBASIC language allows to define and, above all, to allocate space
to keep binary information. This is done with the use of the BUFFER
data type. This type of data is special: in fact, it represents a certain
memory area, of a certain size and starting from a certain position in
the memory.
Defining a BUFFER is simple, because it is sufficient to use the following
syntax:
1 ... = #[ a a 5 5 a a 55 a a 5 5 a a 5 5 ]

The sequence of hexadecimal digits in square brackets describes the

contents of the buffer. In this specific case, we are defining a memory
area of 8 bytes, with an alternating pattern of &H55 (85 decimal) and
&Haa (170 decimal) values.

3.1.10 Assignment

When working with variables in ugBASIC, it is essential to understand

the concept of assignment. Assignment is the act of assigning a value
to a variable. But depending on the symbol used, there are two main
ways to do this: ”by reference” or ”by copy”.

By copy

In assignment by copy (the default behaviour), a new copy of the value

you want to assign is created. This new copy is then stored in the
destination variable. So changing the value of the copy does not change
the original value.
1 a = 42
2 b = a
3 b = 84

56
 3.1 Syntax

4 PRINT a , b : ’ prints 42 and 84

This is the default behavior of ugBASIC. It is useful when you want to

create an independent copy of a value. It is safer because it prevents
accidental changes to variables that you do not intend to change, but
it is harmful when you manage resources, like images or music.

By reference

In assignment by reference, on the other hand, you create an alias or

a ”reference” to the original variable. This means that both variables
refer to the same memory space. So, changing one of the two variables
also changes the other.
1 a = NEW IMAGE (16 ,16)
2 b := a
3 PUT IMAGE b : ’ b and a are the same image

It can improve performance because it avoids creating unnecessary

copies of large data structures, like images or music.

3.1.11 Abbreviations

Abbreviations are a clever way to save memory, and to make a com-

pacted source code. Shorthands are shorter keywords that stood in for
full words. For example, instead of writing PRINT, you could write ?.
This was especially useful on 8-bit computers, where memory was lim-
ited and every byte counted. On ugBASIC this aspect is less important,
but it is important to join some competitions, like the ”BASIC 10Liner
Contest”.
Click here to know more about BASIC 10Liner Contest:
https://ugbasic.iwashere.eu/10liner

57
 3 ”BASIC” concepts

This manual reports the abbreviations that can be used.

1 ’ Without abbreviations
2 CLS
3 i = 0
4 WHILE i < 10
5 PRINT i
6 INC i
7 WEND
8
9 ’ With abbreviations
10 Cl : i = 0: Wh i <10:? i : INCi : We

3.1.12 Conditional compilation

Imagine you have a program that needs to run on different targets.

Instead of creating completely separate versions of the very same pro-
gram, you can use conditional compilation. This technique allows the
compiler to select and include only certain parts of the source code
during compilation, based on specific conditions or definitions.
The first available syntax allows you to indicate which of the targets
supported by ugBASIC will be compiled:
1 ... ON target1 , target2 , ...

The second available syntax allows you to indicate which of the targets
supported by ugBASIC will not be compiled:
1 ... ON ALL BUT target1 , target2 , ...

Targets names are the same but in UPPERCASE.

With this instruction you can write specific code for a particular target
or processor, or available function (like the presence of a joystick). In
this way, you can include or exclude certain features of the program
depending on the needs of system configurations.
Conditional compilation applies only to some instructions:

58
 3.1 Syntax

• AFTER...CALL
• AFTER...GOSUB
• ASM

• CALL
• EVERY...CALL
• EVERY...GOSUB

• DECLARE
• EVERY ON
• EVERY OFF
• KILL

• PARAM
• PROCEDURE
• RESPAWN
• SPAWN

• SYS

59
3 ”BASIC” concepts

3.2 Data types

3.2.1 Integers

In ugBASIC the integer types are closest to the manipulation capabilities

of the retrocomputer. Integers are numbers without the decimal point.
They are represented by one or more bytes, depending on the maximum
value, and may or may not have a sign (relative numbers).

The first integer data type is BYTE, that is a number of 8 bit. The
choice of 8 bits as the standard byte size was made for several histor-
ical and practical reasons, since 8 bits are sufficient to represent most
alphanumeric characters using codes such as ASCII.

The architecture of early computers lent itself well to working with

groups of 8 bits, so byte is a convenient size for organizing memory and
data within a computer. In 8-bit computers, the byte was the basic unit
with which the processor works. This meant that processor’s registers,
which are like small internal memories, were 8 bits wide. The data bus,

60
 3.2 Data types

which transports data between the processor and memory, is a multiple

of 8 bits wide. Memory addresses were often expressed in bytes.
A BYTE can represent a single character, such as a letter or number,
could be represented with a byte. Integers between 0 and 255 could
be represented directly in a byte and, if signed is implemented, integers
between -127 and 127, too.
The next integer type is INT (also known as INTEGER and WORD). A word
is a unit of information made up of 16 bits. Because it is larger than a
byte, it can hold more data. A memory address occupy 16 bits, allowing
access to 65,536 different memory locations. A 16-bit word allowed you
to represent larger integers than a byte, up to 65,535 (withoud sign)
and 32,767 (with sign). Many processor instructions were designed to
operate on 16-bit words.
Finally, the last integer type is LONG (also known as DWORD). It is a data
type that is 32 bits long. Because it is larger than both a byte and a
16-bit word, it can hold even more data. This data represent very large
numbers, with integers up to 4,294,967,295 (without sign), providing a
much wider range than a 16-bit word. In 8-bit computers, the 32-bit
double word was often used indirectly or simulated.

The ugBASIC language provides a default data type for integers. This
type is called the ”default type”. If you do not specify a different
type, the default type is INT (SIGNED WORD). However, it is possible to
change the default type with the OPTION DEFAULT TYPE command:
1 DEFINE DEFAULT TYPE LONG

When you type a number in the source code (as a constant), i.e. 42,
it is implicitly converted to a numeric type using the standard (wide)
approach, that converts the number in a 2 byte value, or better, into the
default data type. It is also available a optimized (narrow) approach,
that converts the number in the most compact space, i.e. 1 byte.
The first approach is the standard one, which can be strengthened

61
3 ”BASIC” concepts

with the OPTION TYPE WIDE command: in this mode, the number is
converted into the default data type, which is the INT (SIGNED WORD)
type, and it occupies 2 bytes.
The second approach is the optimized one, which can be selected with
the OPTION TYPE NARROW command: in this mode, the number is con-
verted into the smallest data type capable of containing the number.
So 42 is converted to a SIGNED BYTE value that occupies 1 byte.
Note that fact that, in the latter case, it is necessary to consider that,
if you also want to take signed types into consideration, the smallest
data could be the immediately higher one, precisely due to the need to
represent the sign bit: so 150 will be translated to SIGNED WORD since
is greater than 127.
If you want to change this behaviour, you can use the OPTION TYPE
UNSIGNED command, and the 150 will be converted into a simple (un-
signed) BYTE.
Other important facts about integer types:

• BYTE and CHAR are the most efficient data type, since it is the
data type more similar to the one managed by 8 bit CPUs. The
BYTE is typically used as array indices and loops. The CHAR is
used for single character;
• SIGNED BYTE is the signed version of BYTE: it means that support
any negative and boolean values (TRUE is -1 and FALSE is 0);
• WORD offers an higher range of positive values with fast computa-
tion performances;

• INT (or INTEGER or SIGNED WORD) offers an higher range of val-

ues and they support negative numbers, although it is fast but
not faster than WORD;
• ADDRESS is similar to WORD but it can be used to specify memory

62
 3.2 Data types

addresses, like in POKE or PEEK commands;

• DWORD offers an even higher range of positive values, but it is
slower than WORD;

• SIGNED DWORD (or LONG) offers an higher range of values and

they support negative numbers, although it is not faster than
DWORD.

3.2.2 Numbers and numerals

Numbers (numeric literals) can be written in any of the following num-

beral systems: decimal, hexadecimal and binary. Each form can be
expressed in various ways. As described by the previous chapter, bi-
nary and hexadecimal numbers are assumed unsigned or signed based
on default data type.

Hexadecimal, or base 16, is a numbering system that uses 16 digits (0

through 9 and the letters A through F) to represent numbers. This
system is widely used in computing, especially to represent memory
addresses, colors, and character codes. Moreover, it is a concise way
of representing binary numbers, which are the basis of how computers
work, and bit-level operations are often easier to display and manipulate
in hexadecimal.

63
 3 ”BASIC” concepts

3.2.3 Floating point

In ugBASIC, the FLOAT data type is used to represent floating-point

numbers. This means that they can represent both whole numbers and
numbers with a decimal part, such as 3.14, -2.5, or even very large or
very small numbers in scientific notation (for example, 1.23E-5). The
term ”float” comes from English and means ”floating”. The idea is that
the decimal point can ”float” in different positions within the number,
allowing it to represent a wide range of values.
Using FLOATs in ugBASIC is similar to using other data types. You
declare variables of type float and assign value to them.

1 x = 3.14
2 y = -2.5 E6 : ’ Equals -2.5 * 10^6
3 PRINT x + y

The precision of a FLOAT number depends on the number of bits used

to represent it. In general, the more bits used, the greater the precision.
The precision is important because it affects the representation of num-
bers and the results of calculations. A number with a lower precision
may not be represented exactly, which can lead to rounding errors in
calculations. Currently ugBASIC supports different precision, based on
the CPU used. It currently supports 24-bit (FAST) and 32-bit (SINGLE).
Note that, because of the binary representation of float numbers, round-
ing errors can occur. These errors are unavoidable and become more
significant when performing many calculations or when using very large
or very small numbers. Moreover, FLOATs numbers have a limited range
of representable values. Numbers that are too large or too small can
cause an overflow or underflow. Finally, arithmetic operations on floats
are slower than integer operations.

64
 3.2 Data types

3.2.4 Bits

The BIT data type is the smallest unit of information in a computer. It

can only take two values: 0 or 1. Think of it as a switch that can be
on (1) or off (0).
Although the ”BIT” is the smallest unit, it is the basis of everything
a computer does. Every file, image, video, or program is, ultimately, a
long sequence of ”BIT”S. They take up very little memory, since they
are ”packed” on the minimum number of bytes.
The ”BIT”s are fundamental for the boolean logic with flags, and they
are implictly converted to TRUE or FALSE, when used. These can be
used to create compact and efficient data structures, such as ”bitsets”,
just using them in an array.

3.2.5 Strings

Strings are fixed-length or variable length series of ASCII characters.

You can define (fixed) length strings by enclosing text inside double
quotes (”):
1 " this is a static string !"

You can assign fixed string to variables, and this will transform them in
dynamic strings:
1 x = " this is a dynamic string !"
2 MID$ (x , 1 , 4) = " that "
3 PRINT x : ’ it will print " that is a dynamic string !"

Depending on which target you are considering, dynamic strings can be

a maximum of 255 characters or 127 characters long, and take up to
1024 bytes. You can change this overall limit. Furthermore, ugBASIC
is able to handle a maximum of 256 (or 128) different ones at the same

65
 3 ”BASIC” concepts

time, and you can change this limit, too. There is no limit for static
strings.
In order to optimize the occupied memory, or to increase the possibilities
of the language, it is possible to define the maximum number of dynamic
strings that the language must be able to process. This is done with
the DEFINE STRING COUNT instruction:
1 DEFINE STRING COUNT 100

The maximum value is 128 on targets based on MOTOROLA 6809 and

256 on all the other targets.
In general, each dynamic string needs 4 bytes to be fully described, in
addition obviously to the space occupied by the actual characters of
the string itself. This means that, if the maximum number of strings
that can be processed simultaneously is set as 100, as in the previous
example, they will occupy 400 bytes.
In order to optimize the occupied memory, or to increase the possibilities
of the language, it is possible to define the maximum space allocated
for dynamic strings that the language must be able to manage. This is
done with the DEFINE STRING SIZE instruction:
1 DEFINE STRING SIZE 1024

The maximum value depends on the available memory. Moreover, to

manage dynamic garbage collection, we realize that the space occu-
pied will actually be double. So, in the previous example, the effective
memory used by strings will be 2048 bytes

3.2.6 Resources and buffers

In ugBASIC the graphical data, the audio data and any other programs’s
resource is managed by specific data types, that acts as an ”handle” for
the real data. Since the language is isomorphic, it hides the meaning of

66
 3.2 Data types

this handles in a such way that you can only use them in a isomorphic
way. The only resource that is not specialized is BUFFER.

The BUFFER data type is used to represent a memory area of any kind,
from a spare memory to a specific and big resource. Currently, you
are not able to manipulate this kind of data type in way different from
defining them and using them when you need them. Obviously, you
can copy a buffer in another, assign it, compare or convert into another
kind of resource, like IMAGE, but it is done by compiler at compilation
time.
To define a buffer you can use the explicit method, like this:
1 ’ this define a buffer of 4 bytes , each of $42 ( hexadecimal )
2 x = #[42424242]
3
4 ’ the same , but you can omit the last character
5 x = #[42424242

67
 3 ”BASIC” concepts

Alternatively, you can define a BUFFER using a string. In that case,

embedded sequences can be used to represent non-printing characters:
1 ’ this define a buffer of 4 bytes , each of $42 ( hexadecimal )
2 x = " {4 2 } { 4 2 } { 4 2 } { 4 2 } "

The advantage of strings is that they can be added together, and there-
fore broken into multiple lines. Additionally, you can use auxiliary func-
tions such as Z(...), which allows you to generate sequences of zeros.
You can also use the implicit method, by loading the buffer from an
external file:
1 x = LOAD (" buffer . dat ")

Now you can convert the buffer into an image or animation by ”casting”
it:
1 x = ( IMAGE ) LOAD (" image . bin ")
2 x = ( IMAGES ) LOAD (" images . bin ")

Note that is not a ”real” conversion, but it is only a formal conversion.

The data contained in ”image.bin” and ”images.bin” must be valid
binary data image(s) for the current target. Since they changes very
deeply, in order to be optimized for each target, we must avoid to do a
formal convert and we need to make a substantial conversion. This is
done by the various LOAD primitives, that are able to load and convert
data at the same time, generating valid handles.

68
 3.3 Variables and constants

3.3 Variables and constants

3.3.1 Variables

So, let’s start by the fact that ugBASIC is a dynamic programming

language (as any standard BASIC language), so you can use variables
without defining them before the use, by using the automatic definition.
Infact, if an undefined variable is used into the source, ugBASIC com-
piler will try to define it silently, deducing the data type based on the
type of the expression / constant used to initialize the variable.
For example:
1 a = 42
2 PRINT a

The above example will be compiled because ugBASIC defines the vari-
able a in the line 1. This means that ugBASIC can work also if no
variable is defined. Obviously, you can also define them before they’re
used, and this is called ”manual definition”.

The VAR or DIM statement may be used to explicitly define variables.

Here are some examples of variable definition using VAR/DIM:
1 VAR lines AS INTEGER
2 DIM scoring AS WORD
3 VAR why AS LONG
4 DIM surname AS STRING

Apart from the VAR/DIM statement, there are other cases where you
may explicitly define a variable. Assigning values to variables by using
a suffix symbol (the , %, &, $ suffixes) is supported in ugBASIC.
1 a@ = -120
2 a %=42
3 a &=239485838

69
 3 ”BASIC” concepts

When a variable is defined with a type, it can be accessed only with the
correct suffix.
In ugBASIC there is also a way to force that variables are defined before
using them. It is the OPTION EXPLICIT statement. This command can
be used ad any point of the program, to force to declare all the variables
before using them. When you add this statement alone, ugBASIC will
emit a compile error and it highlight the variable in the code that need
to be declared. Anyway, it can be also disabled using the OFF parameter:
1 OPTION EXPLICIT ON
2 PRINT a : REM this is an error !
3 OPTION EXPLICIT OFF
4 PRINT a : REM this is * not * an error !

Like other BASICs, variables are automatically initialized to 0. This

means that you can assume that the initial value of a variable will be
always zero (0). until you have assigned some value to it.
1 a = 5
2 a = a + 1000
3 PRINT a , b

3.3.2 Variables scope

Variables can be defined everywhere, but you must take care of the
fact that the position of variable definition defines the “scope” of the
variable or its visibility. In ugBASIC we have only two scopes:

• global scope (GLOBAL or SHARED keywords), so the variable is

visible everywhere in the program, from main source to every
PROCEDURE
• local scope, where the variable is visible only inside the PROCE-
DURE or inside the main program, as well

If you define a variable outside a PROCEDURE, it will be defined inside

the main program (in its ”local” scope), which means that it will be

70
 3.3 Variables and constants

not accessible by PROCEDUREs. To make it accessible, you need to

use the GLOBAL keyword in main source or SHARED keyword inside the
PROCEDURE. If you define a variable inside a PROCEDURE, it will be de-
fined in the local scope of that PROCEDURE and it won’t be accessible
from anywhere else.

3.3.3 Constants

Constants are literals that will be translated into numeric / string values
at compile time. When the compiler encounters a constant, it will take
the real value represented. Constant are always ”global”, i.e. are visibile
everywhere.
To define a constant you use the keyword CONST
1 CONST maximumValue = 15000

The ugBASIC compiler is compatible also with other (and valid) key-
words, like SHARED CONST, CONST SHARED, GLOBAL CONST and CONST
GLOBAL.
There are many benefits in using contants:

• they do not take memory;

• they will be evaluated once by compiler;

• they can be used for asserting;
• they will speed up program execution.

3.3.4 Asserting using constants

An ”assertion” is a boolean expression that must be “true” if and only

if the code is working correctly. If the assertion is false, an error is

71
 3 ”BASIC” concepts

reported the code needs to be corrected. Assertions allow you to insert

a ”sanity check” mechanism. These controls are used in the testing and
development phase.
The ugBASIC language allows to define constant that must be positive
(POSITIVE):
1 ’ Check that this target has 300 pixel of width , at least
2 POSITIVE CONST checkWidth = SCREEN WIDTH - 320

Moreover, the programmer can specify a range of values([,],(,],[,),(,)).

1 ’ Check if the value is between 1 and 9 , inclusive
2 CONST checkValue IN (0 ,10) = value
3 ’ Check if the value is between 0 and 9 , inclusive
4 CONST checkValue IN [0 ,10) = value
5 ’ Check if the value is between 1 and 10 , inclusive
6 CONST checkValue IN (0 ,10] = value
7 ’ Check if the value is between 0 and 10 , inclusive
8 CONST checkValue IN [0 ,10] = value

If the constants are out of ranges, the compilation will stop.

3.3.5 Type conversion (casting)

Imagine you have a glass of water and you want to pour it into a smaller
bottle. Not all the water fits in there. In the world of programming,
this ”pouring” is called ”casting” (or ”type conversion”).
In computer science, casting is the act of converting one type of data
into another. For example, you might want to convert an INTEGER to
a BYTE, or vice versa.
Since memory is limited and every bit counted, casting was often neces-
sary to make better use of memory. Converting data to a smaller type
could save space, while some calculations require special data types.
Many external devices expected data in a specific format.
Casting is not always a ”safe operation”: if you try to cast a value to a

72
 3.4 Strings

smaller type, you can lose information. For example, if you cast a LONG
to a BYTE, the most significant part of the number will be truncated.
The compiler can automatically perform the casting when it is sure that
no data will be lost, but it could increase executable size and decrease
performances. In other cases, you must explicitly specify the casting
using the casting operator:
1 DIM x AS INTEGER , y AS BYTE
2 x = 1024
3 ’ This type conversion will lose the high part of the integer .
4 y = ( BYTE ) x

3.4 Strings

This section will show you how to handle strings through instructions.
Infact, ugBASIC has a full range of string manipulation instructions,
and experienced Basic programmers should already be familiar with the
standard syntax used.

3.4.1 Extracting and replacing chars

The first that we show is LEFT$ (also shortened as LEFT). It reads the
specified number of characters in a source string, starting from the left-
hand side, and copies them into a destination string. The first type of
usage of this function creates a new destination string from the chosen
number of characters of the source string.
1 a = " ugBASIC COMPILER "
2 b = LEFT$ ( a , 7 )
3 PRINT b : REM It print out " ugBASIC "

The second usage is to replace the leftmost number of characters:

1 a$ = "******* COMPILER "
2 LEFT$ ( a$ , 7 ) = " ugBasic "
3 PRINT a$ : REM It print out " ugBASIC COMPILER "

73
 3 ”BASIC” concepts

Exactly the same processes can be performed with the other side of the
string by using the RIGHT$ (RIGHT) function:
1 a$ = " ugBASIC ********"
2 RIGHT$ ( a$ , 7 ) = " COMPILER "
3 PRINT a$ : REM It print out " ugBASIC COMPILER "
4 b$ = RIGHT$ ( a$ , 7 )
5 PRINT b$ : REM It print out " COMPILER "

Similarly, the MID$ (also abbreviated as MID) function returns char-

acters from the middle of a string, with the first number specified in
brackets setting the offset from the start of the string and the second
number setting how many characters are to be fetched. If the number
of characters to be fetched is omitted from your instruction, then the
characters will be read right up to the end of the string being examined.

Some examples:
1 PRINT MID (" ugBASIC " , 6) : REM it prints out " C "
2 a = " ugBASIC "
3 MID (a , 6 , 1) = " X "
4 PRINT a : REM " ugBASIX "

3.4.2 Finding characters in a string

If you need to search through strings for individual characters or sub-

strings, there is a specific instruction, called INSTR. This is very useful
if you want to write an adventure game where lines of text must be
broken down into individual commands. INSTR allows you to search for
all instances of one string inside another.
In the following examples, the first string is searched for the first occur-
rence of the second strings. If it is found, its location will be reported
in the form of the number of characters from the left-hand side of the
searched string. If the search is unsuccessful, a result of zero will be
given.
1 PRINT INSTR ( " ugBASIC " , " ugBASIC ") : REM Print 1
2 PRINT INSTR ( " ugBASIC " , " O ") : REM Print 0

74
 3.4 Strings

3 PRINT INSTR ( " ugBASIC " , " A ") : REM Print 4

Normally, the search will begin from the first character at the extreme
left-hand side of the host string, but you can specify an (optional)
number of characters from the beginning of the searched string. The
optional start-of-search position can range from zero to the maximum
number of characters in the searched string to be searched.
For example:
1 PRINT INSTR ( " ugBASIC " , " ugBASIC " , 2) : REM Print 0
2 PRINT INSTR ( " ugBASIC " , " A " , 3) : REM Print 4
3 PRINT INSTR ( " ugBASIC " , " A " , 5) : REM Print 0

3.4.3 Converting strings

When you need to convert the characters in a string into upper case
(capital) letters, you can use the UPPER$ (shortened as UPPER) func-
tions that generates a new string. The same if you need to convert to
lower case a string, by using LOWER$ (LOWER). There commands have
also an alias as UCASE$ and LCASE$. These sorts of text conversions
are particularly useful for interpreting user-input in interactive data pro-
grams and adventure games, because input can be converted into a
standard format which is understood by your programs.
1 PRINT UPPER$ (" ugBasic ") : REM it prints out " UGBASIC "
2 PRINT LOWER$ (" ugBasic ") : REM it prints out " ugbasic "
3 PRINT UPPER$ ( LOWER$ (" ugBasic ") ) : REM it prints out " UGBASIC "

In ugBASIC numbers can be converted into strings by using the STR$

(shortened as STR) function. This can be used to overcome some limita-
tions posed by functions which does not accept numbers as parameters,
but will work happily with parameters in the form of strings. Also, when
string adding is performed, all operand must be strings.
It is an example:

75
 3 ”BASIC” concepts

1 REM It prints out " The answer is 42"

2 PRINT " The answer is " + STR$ (42)

To perform the reverse task, you can use the VAL function. It converts
a list of decimal digits stored in a string, changing them into a number.
Note that a result of zero is returned if this process fails for any reason.
For example:
1 x = VAL ("42") : PRINT x : REM it prints 42
2 y = VAL (" is42 ") : PRINT y : REM it prints 0

Finally, the STRING$ function (abbreviated as STRING) can be used to

create a new string filled with the required number of copies of the first
character from an existing string. The following example produces a
new string containing ten copies of the character “u”.
1 PRINT STRING (" ugBASIC is a compiler " ,10)

3.4.4 Manipulating strings

There are some functions to handle string in a very special way. For
example, you can produce a certain number of spaces by using the
function SPACE$ (SPACE). Or you could flip your string, reversing the
order of letters, by simply calling FLIP$ (or FLIP). For example:
1 PRINT FLIP$ (" ugBASIC ") : REM print out " CISABgu "
2 PRINT FLIP$ ( FLIP$ (" ugBASIC ") ) : REM print out " ugBASIC "

3.4.5 Getting information about strings

The CHR$ function creates a string that contains a single character,

generated by a given ASCII code number. Note that, depending on the
hardware, only some characters are printable on the screen. Others are
used internally as control codes. For example:

76
 3.5 Arrays

1 i = 0: FOR i = 32 TO 255: PRINT CHR ( i ) : NEXT

On the opposite side, if you need to get the internal ASCII code of the
first character in a string, you can use the ASC function:
1 PRINT ASC (" A ") : REM print out 65

Finally, the LEN function returns the number of characters stored in a

string.
1 a = " ugBASIC "
2 PRINT LEN ( a ) : REM print out 7

3.5 Arrays

It is often necessary to use a whole set of similar variables for something

like a table of soccer results or a catalogue for a record collection. Any
set of variables can be grouped together in an ”array”.

3.5.1 Defining an array

Supposing you have 100 titles in your record collection, and you need
to size the set of variables needed for your array. There is a special
command for setting up this dimension.

The DIM command is used to dimension an array, and the variables in

your record collection table could be set up with a first line like this:
1 DIM artist$ (100) , title$ (100) , year (100) , price (100)

So, artist$, title, and so on, are the names of the arrays, while 100 is
the size.

77
 3 ”BASIC” concepts

Each dimension in the table is held inside round brackets, and if there is
more than one element in a dimension each number must be separated
from the next by a comma.
1 DIM chessboard (8 ,8)

This command will define a two-dimensional array, i.e. a matrix. Ele-

ment numbers in arrays always start from zero, so the first entry must
be indexed using 0, while the last entry can be accessed using the size
minus one:
1 artist$ (0) =" Cindy Lauper "
2 title$ (0) =" Girls Just Want To Have Fun "
3 year (0) =1983
4 price (0) =10
5 artist$ (99) =" David Bowie "
6 title$ (99) =" Space Oddity "
7 year (99) =1967
8 price (99) =8

Accessing array members is done using the standard BASIC syntax,

taking care that array indices starts from zero (0), so the first element
is 0, the second is 1 and so on. Note that no boundary check is done
at runtime. So, if you use a set of indexes that are out of the limits of
the array, the program probably crashes.
To extract elements from any array, you could then add something like
this to your example program:
1 PRINT title$ (0) : PRINT price (0)
2 PRINT title$ (99) : PRINT year (99) : PRINT price (99)

3.5.2 Bounds of an array

These tables can have up to 256 dimensions as you like, and each
dimension can have up to 65.535 elements. The size of the array is
actually limited by the available memory, which is different depending
on the retrocomputer used.

78
 3.5 Arrays

Here are some examples:

1 DIM list (5) , number (5 ,4 ,3) , word$ (5 ,5)

Once you define an array, you cannot change its size dynamically at
runtime. However, it is possible to programmatically know what is the
maximum value of the index is by using the UBOUND statement. The
syntax for the given arrays follows:
1 PRINT UBOUND ( number ) : REM 5

If the array has more than one dimension, you can get the size of a
specific dimension by putting it after the array’s name:
1 PRINT UBOUND ( number ,0) : REM it is like UBOUND ( number )
2 PRINT UBOUND ( number ,2) : REM is 3

There is also an instruction to know the minimum value of the index

(LBOUND), but this value will always be 0.

3.5.3 Type an array

It is possible to define the ”type” of the elements of an array, which

must be the same for all elements. The ugBASIC language allows you
to define the type in three ways: implicitly, explicitly, and in full.
The implicit way occurs by calling the DIM instruction without indicating
any type: in this case, ugBASIC will use the default type which is INT
(signed 16-bit value).
1 DIM integers (42)

You can change the default type with the OPTION DEFAULT TYPE state-
ment, and this change will be reflected in the next DIM statement.
1 DIM integers (42)
2 OPTION DEFAULT TYPE LONG
3 DIM longs (42)

79
 3 ”BASIC” concepts

The explicit way is to use, at the end of the array name, a symbol that
indicates the type: the dollar sign ($) for strings, the percentage symbol
(%) for integers, and so on. Note that once the type is defined in this
way, it is not necessary to use the symbol to refer to the array, as the
type is understood to be defined by the DIM, and cannot be changed
at runtime.
1 DIM strings$ (42)
2 DIM integers %(42)
3 integers (10) =21 : ’ type is implicitly INT
4 strings (10) =" test " : ’ type is implicitly STRING

The complete way is to use the AS keyword, which allows you to specify
the type of each element precisely and punctually.
1 DIM strings (42) AS STRING
2 DIM integers (42) AS INT

3.5.4 Initialize an array

When you define an array, it is filled with zeros (if it is numeric) or

empty strings (if it is string). It is possible, for numeric arrays, to fill it
with different values, so that it assumes them when the program starts.
There are various ways to initialize arrays.
The simplest way is to directly indicate the constant to use, with the
WITH keyword. In this case, this value will be assigned to all elements
of the arrays. Example:
1 DIM integers (4) WITH 42
2 PRINT integers (1) : ’ will print "42"

Another way is to indicate, explicitly and individually, the elements of

the array. In this language arrays are organized first by rows and then
by columns.

80
 3.5 Arrays

In practice, first the elements with the rightmost dimensional index

are stored consecutively, then gradually towards the left, until the last
element.
1 DIM integers (3 ,2) = #{ 10 , 20 , 30 , 40 , 50 , 60 }
2 PRINT integers (1 ,0) : ’ will print "30"

An alternative way is to define byte by byte the memory area that will be
occupied by the array: in this case, it is necessary for the programmer
to know how the ugBASIC array is organized.

In the current implementation, arrays are contiguous memory areas,

where the elements are organized exactly as they are from a logical point
of view. Therefore, assuming that the default type is INT and wanting
to fill it statically at the beginning of the program, it is sufficient to
insert the 60 bytes, two bytes for each element.

81
 3 ”BASIC” concepts

The syntax for initializing an array in this way is the sequence #[...],
where the last parenthesis is optional, and each byte must be defined
with two hexadecimal digits. For example:
1 DIM integers (3 ,2) = # [ 0 0 1 0 0 0 2 0 0 0 0 3 0 0 0 4 0 0 0 5 0 0 0 6 0 ]
2 PRINT integers (1 ,0) : ’ will print "48" ("30" is hexadecimal !)

Note that this way of initializing an array is not isomorphic, in the sense
that it must adapt to each type of processor. In particular, if you need
to initialize values larger than one byte, it is important to consider their
order within the processor. In this regard, there are two constants,
LITTLE ENDIAN and BIG ENDIAN which allow us to know the order in
which they must be defined.

Finally, it is possible to load a text file (in a sort of ”CSV” type format)
with the LOAD ... AS TEXT instruction.
1 DIM integers (4) = LOAD " numbers . txt " AS TEXT

When initializing a vector (i.e. an array with a dimension), you can omit
the dimension, because ugBASIC will automatically calculate it based
on the data used to initialize it.
1 DIM integers () = # [ 0 0 1 0 0 0 2 0 0 0 3 0 0 0 4 0 ]

Note that retrocomputers may have little RAM available to store data,
and arrays may never need to change during code execution. This is
especially true for arrays used as ”game maps”. In that case, you can
tell ugBASIC that the array will be ”read-only”, and therefore that it
shouldn’t take up any space. This is possible with the use of the READ
ONLY (or READONLY) keyword.
1 DIM gamemap () = #[10203040] READ ONLY

3.5.5 Filling an array

For arrays that are not ”read-only”, you can modify them during pro-
gram execution, either punctually or massively. The simplest way is to

82
 3.6 Maths

use the ARRAY command to reinitialize the array, exactly as was done
with the DIM command.
1 DIM integers (3 ,2) = #{ 10 , 20 , 30 , 40 , 50 , 60 }
2 PRINT integers (1 ,0) : ’ will print "30"
3 ARRAY integers = #{ 53 , 21 , 10 , 00 , 00 , 00 }
4 PRINT integers (1 ,0) : ’ will print "10"

Clearly, if you have two variables of the same type and size, you can
copy one on the other.
1 DIM integers1 (3 ,2)
2 DIM integers2 (3 ,2)
3 integers2 = integers1

Alternatively, if you want to fill an array with the same value, for example
to reset it to zero, you can use the FILL command.
1 DIM integers (3 ,2) = #{ 10 , 20 , 30 , 40 , 50 , 60 }
2 PRINT integers (1 ,0) : ’ will print "30"
3 FILL integers
4 PRINT integers (1 ,0) : ’ will print "0"
5 FILL integers WITH 42
6 PRINT integers (1 ,0) : ’ will print "42"

Arrays is a vector or a matrix of values, and they are similar to the

arrays of other basics. They must be explicitly defined using the DIM.
The maximum number of dimensions is 256. A few examples of defining
arrays:
1 DIM AS BYTE vettore (52)
2 DIM numbers (5)
3 DIM ipermatrix (5 , 5 , 5)

3.6 Maths

3.6.1 Arithmetical calculations

Traditional mathematical operation is very easy on ugBASIC, since it

gives to the programmer all basic arithmetical operations. For example,

83
 3 ”BASIC” concepts

this instruction will print out a simple 4 as a result:

1 PRINT 2+2

The ugBASIC language recognize various mathematical symbols, as

follows:

• + : the plus sign that always signals addition;

• - : the minus sign, used for subtraction;

• * : the asterisk sign for multiplication;
• ** : the double asterisk sign for multiplication with a number
that is a power of 2 (very fast on CPU);

• / : the forward-slash symbol for division;

• \ : the backward-slash symbol for division with a number that is
a power of 2 (very fast on CPU);
• ^ : the circumflex character as exponential symbol (raise this
number to a given power);

The following two lines are equal:

1 a = 3^5
2 b = 3*3*3*3*3

The following logical operations can also be used in calculations:

• MOD : is the ”modulo” operator;

• NOT : is the bit a bit / logical not;

• AND : is the bit a bit / logical and;

• OR : is the bit a bit / logical or;
• XOR : is the bit a bit / logical exclusive or

84
 3.6 Maths

Note that ugBASIC uses the convention, very common in BASICs of the
1970s and 1980s, of considering Boolean logic as implemented through
the so-called ”two’s complement”.
In other words, the value FALSE is associated with a number composed
of all 0s, in terms of bits. The value TRUE is, instead, associated with a
number composed of all 1s, again in terms of bits. According to the 2’s
complement representation, a number composed of all ones is always
equivalent to the number -1, regardless of how many bits the number is
composed of, while a number composed of all zeros is always equivalent
to zero.
According to this convention, there is a coincidence between bitwise
and logical operations: in fact, a bitwise AND, applied to all the bits of
the number, will be equivalent to the logical operation ”and”. And so
with the remaining bitwise (/logical) operations.

3.6.2 Calculation priorities

Since arithmetical instructions are taken literally, ugBASIC uses a set

of built-in priorities. So the following lines give the results 6 and 8,
respectively:
1 PRINT 2+2*2 : REM Print 6
2 PRINT (2+2) *2 : REM Print 8

The ugBASIC language handles a combination of calculations that make

up an ”expression” in the following strict order of priority:

• exponential (^) are always calculated first;

• multiplications (*) and divisions (/) are then calculated in order
of appearance, from left to right;
• the the modulo operations (MOD) is elaborated;

85
 3 ”BASIC” concepts

• additions (+) and subtractions (-) are calculated last, again in

order, from left to right;

Note that logical operations above (NOT, AND, OR, XOR) will not be taken
into account until after all the above calculations have been completed.
Obviously, any calculation placed inside a pair of round brackets is
evaluated first, and treated as a single number.
So the next calculation gives a result of 43:
1 PRINT 10+2*5 -8/4+5^2 : REM Print 43

This is the order followed:

1 5^2 = 25
2 2*5 = 10
3 8/4 = 2
4 10+10 = 20
5 20 -2 = 18
6 18+25 = 43

By adding two strategic pairs of brackets to the same calculation, the

logical interpretation is transformed, resulting in an answer of 768 (!),
like this:
1 PRINT (10+2) *(5 -8/4+5) ^2 : REM Print 768

This is the different order followed:

1 10+2 = 12
2 5 -8/4+5 = 5 -2+5
3 5 -2+5 = 8
4 8^2 = 64
5 12*64 = 768

3.6.3 Fast calculations

Mathematical calculations typically generate a series of intermediate

values, and can therefore sometimes be a little slow. There are three

86
 3.6 Maths

instructions that can be used to increase the speed when it is present a

simple calculation:

• INC - to increment a variable by 1;

• DEC - to decrement a variable by 1;

• ADD - to add any number to a variable;

INC command adds 1 to an variable, using a single instruction to per-

form the expression variable=variable+1 very quickly.
For example:
1 v =41 : INC v : PRINT v

Similarly to INC, the DEC command performs a rapid subtraction of 1

from an integer variable.
1 v =43 : DEC v : PRINT v

Finally, the ADD command can be used to add the result of an ex-
pression to a whole number variable. It is the equivalent to make a
variable=variable+expression but performs the addition faster.
There is a more complex version of ADD, which is ideal for handling cer-
tain limits much more quickly than the equivalent separate instructions.
When those other parameters are included,
1 ADD v ,a , b TO t

is the equivalent to the following lines:

1 v=v+a
2 IF v < b THEN v = t : ENDIF
3 IF v > b THEN v = b : ENDIF

Here is an example:
1 v =0
2 REPEAT
3 ADD v ,1 ,1 TO 42
4 PRINT v
5 UNTIL v == 43 : REM This loop is infinite because v < 43

87
 3 ”BASIC” concepts

3.6.4 Relative values

It is obvious that every expression has a value, but expressions are

not restricted to whole numbers (integers), or any sort of numbers.
Expressions can be created from real numbers or strings of characters.
If you need to compare two expressions, the following functions are
provided to examine them and establish their relative values.
The MAX instruction compares two expressions and returns the largest. It
can be used with any type of expressions, but they cannot be compared
if they are mixed.
1 PRINT MAX (99 ,1) : REM Print a 99
2 PRINT MAX (" ugBASIC " ," AAAA ") : REM Print " ugBASIC "

On the very same way, MIN compares two expressions and returns the
smaller value of two expressions.
1 DEBUG MIN (99 ,1) : REM Print a 1
2 DEBUG MIN (" ugBASIC " ," AAAA ") : REM Print " AAAA "

3.6.5 Values and signs

To explain how ugBASIC treats signed numbers, it is necessary to make

a brief excursus on the concept of “two’s complement”. There are 256
possible values in a byte: 00 to FF (in hexadecimal). The range of an
8-bit unsigned number is 0 (00) to 255 (FF). The range of a 16-bit
unsigned number is 0 (0000) to 65535 (FFFF), and so on. They are
called unsigned numbers because they are zero or greater, i.e. there is
no (minus) sign.

A signed number, on the other hand, can be negative or positive (or

zero). The term ”signed number” is used below to mean a two’s com-
plement number, so the range of an 8-bit signed number is -128 to 127.
The values -128 through -1 are, in hex, 80 through FF, respectively.
The values 0 through 127 are, in hex, 00 through 7F, respectively. So

88
 3.6 Maths

the minimum value of a signed number is 80 and the maximum value

of a signed number is 7F. The range of a 16-bit signed number is -
32768 (8000) to 32767 (7FFF) (8000 through FFFF are the negative
numbers), and so on.

This may seem like a strange way of handling negative numbers, but
this method has several useful properties:

• same representation for positive numbers: the ”overlap” of

the ranges of 8-bit signed and unsigned numbers is, in hex, 00 to
7F, regardless of whether the number is signed or unsigned;
• a bit for the sign: the most significant bit (bit 7 for an 8-bit
number) is zero when the number is non-negative (0 to 127), and
one when the number is negative;

• zero is positive: in mathematics, zero is not a postive or a neg-

ative number, but in the computer world, things are less formal;
so the term ”positive number” typically includes zero because (a)
all of the other possible values of a signed number whose most
significant bit is zero are positive numbers, and (b) all of the other
possible values for an unsigned number are positive numbers;
• adding and subtracting is the same.

Any number can have one of three values: negative, positive or zero,
and these are represented by the ”sign” of a number. So the SGN
function returns a value representing the sign of a number. The three
possible results are these:

• -1 if the value is negative;

• 1 if the value is positive;
• 0 if the value is zero.

So:
1 PRINT SGN ( -42) : REM Print -1

89
 3 ”BASIC” concepts

On the other side, ABS can be used to convert arguments into a positive
number. ABS returns an absolute value of an integer or fractional num-
ber, paying no attention to whether that number is positive or negative,
in other words, ignoring its sign.
1 PRINT ABS ( -1) : REM Print 1
2 PRINT ABS (1) : REM Print 1

3.6.6 Random numbers

The easiest way to introduce an element of chance or surprise into a

program is to throw some numbered options into an electronic ”pot”
and to allow ugBASIC to pull one out at random. After a number has
been selected and used, it is thrown back into the pot once again. It
then has the same chance as any other number offered for selection,
when the next random choice is made.
The RND function generates integers at random, between zero and any
number specified in brackets. If your specified number is greater than
zero, random numbers will be generated up to that maximum number.
1 DO
2 x = RND ( WIDTH -1)
3 y = RND ( HEIGHT -1)
4 TEXT x , y , " UGBASIC AT RANDOM "
5 LOOP

In practice, the numbers produced by the RND function are not genuinely
random at all. They are computed by an internal mathematical formula,
whose starting point is taken from a number known as a ”seed”. This
seed is set to a standard value whenever ugBASIC is loaded into your
computer, and that means that the sequence of numbers generated by
the RND function will be exactly the same each time your program is
run.
This may well be acceptable for arcade games, where pre-set random
patterns generated by RND can be used to advantage, but it is a useless

90
 3.7 Control structures

system for more serious applications. The RANDOMIZE command solves

this problem by setting the value of the seed directly. This seed can
be any value you choose, and each seed will generate an individual
sequence of numbers. RANDOMIZE can also be used in conjunction with
the TIMER variable, to generate genuine random numbers.
The TIMER reserved variable is incremented by 1 unit every 50th of a
second (on PAL systems) or by 1 unit every 60th of second (on NTSC
systems), in other words, it returns the amount of time that has elapsed
since your computer was last switched on. As explained above, this
makes it a perfect ”seed” to be used with the RANDOMIZE function, as
follows:
1 RANDOMIZE TIMER

The best place to use this technique is immediately after the user has
entered some data into the computer. Even a simple key-press to start
a game will work perfectly, and generate truly random numbers.

3.7 Control structures

Any programming language gives to the programmer a set of instruc-

tions that allow computer programs to make decisions: they are called
”control structures”. This section will give you a quick overview on the
topic.

3.7.1 Unconditional jumps

One way of forcing programs to jump to a specified locations is to

use the GOTO instruction, followed by a specific target destination. In
ugBASIC destinations can be a literal label or a line number. Label
markers can consist of names that use any string of letters or numbers,

91
 3 ”BASIC” concepts

as well as the underscore character ( ), and they must be ended with

the colon character :.
Take a look at this example:
1 label :
2 COLOR BORDER YELLOW
3 WAIT 100 MS
4 COLOR BORDER BLACK
5 WAIT 100 MS
6 GOTO label

Like any BASIC, also numbers may be used to identify specific lines,
and the program can be commanded to GOTO one of these optional
markers, like this:
1 10 COLOR BORDER YELLOW
2 20 WAIT 100 MS
3 30 COLOR BORDER BLACK
4 40 WAIT 100 MS
5 50 GOTO 10

Note that line numbers could be different from identification numbers,

and labels are much easier to remember and to locate.

3.7.2 Returning from jumps

Routines can be packaged to perform a specific task, and such routines

could be split into smaller set of instructions as ”sub-routines”. GOSUB
is another, also if a bit antiquated, command used to perform a jump
to a sub-routine. As with GOTO, there are two alternative targets for
a GOSUB instruction: labels and line numbers. To make sub-routines
easier to spot in your program listings, it is good practice to place them
at the end of the main.
1 start :
2 GOSUB yellowBorder
3 WAIT 1000 MS
4 GOSUB blackBorder
5 WAIT 1000 MS
6 GOTO start

92
 3.7 Control structures

7 yellowBorder :
8 COLOR BORDER YELLOW
9 RETURN
10 blackBorder :
11 COLOR BORDER BLACK
12 RETURN

When a program execute a GOSUB instruction, it must be instructed to

RETURN to the main program after the subroutine has been executed.
A single GOSUB statement can be linked to several RETURN commands,
allowing exits from any number of different points in the routine.
1 x = 0
2 start :
3 GOSUB incrementX
4 COLOR BORDER x
5 WAIT 500 MS
6 GOTO start
7 incrementX :
8 x = x + 1
9 IF x > 16 THEN : x = 0 : RETURN : ENDIF
10 RETURN

There is no fixed rule. After the RETURN, a jump is made back to the
instruction immediately after the original GOSUB.

3.7.3 Popping returning addresses

Normally, you cannot exit from a GOSUB statement using a standard

GOTO. To avoid this limitation you can use the POP command:
1 x = 0
2 y = 0
3 start :
4 x = x + 1
5 COLOR BORDER x + y
6 GOSUB incrementX
7 GOTO start
8 nextCycle :
9 y = y + 1
10 IF y > 7 THEN : y = 0 : ENDIF
11 GOTO start
12 incrementX :
13 IF x > 7 THEN : POP : x = 0 : GOTO nextCycle : ENDIF

93
 3 ”BASIC” concepts

14 RETURN

It removes the return address generated by a GOSUB, allowing you to

leave the subroutine not using a RETURN statement. In the above ex-
ample, when the color index in x is greater than 7, y is incremented but
outside the original subroutine.

3.7.4 Decision making

The most used command to implement the decision making process

is the IF...THEN...ENDIF structure. It allows simple decisions to be
made within a program, so IF a condition is true THEN the computer
decides to take a particular course of action, up to reach ENDIF. If the
condition is not true, the machine does something else.
The list of condition in an IF...THEN...ENDIF structure can be any
list of tests, including the use of AND and OR keywords. Another keyword
understood is ELSE. This is the ”alternative” choice. Remember that
an IF...THEN...ELSE...ENDIF statement is not limited to a single
line so you can build a ”structured test”.
1 x = 0
2 y = 0
3 start :
4 IF x > 16 THEN
5 y = 0
6 ENDIF
7 IF x = 0 THEN
8 y = 1
9 ENDIF
10 IF y = 1 THEN : x = x + 1 : ELSE : x = x - 1 : ENDIF
11 COLOR BORDER x + y
12 WAIT x * 50 MS
13 GOTO start

In a structured test, each test is set up with an IF and a THEN, and

ended with a matching ENDIF. The statements in a structured test are
separated by colons on any particular line, as usual, but can extend over
any number of lines in your listing, as required.

94
 3.7 Control structures

1 x = 0
2 y = 0
3 start :
4 IF x > 16 THEN
5 y = 0
6 ELSE IF x = 0 THEN
7 y = 1
8 ELSE
9 REM does nothing !
10 ENDIF
11 IF y = 1 THEN : x = x + 1 : ELSE : x = x - 1 : ENDIF
12 COLOR BORDER x + y
13 WAIT x * 50 MS
14 GOTO start

Moreover, there is the capability to allow multiple tests to be per-

formed. The keyword is ELSE IF, and it must be used within a normal
IF...ENDIF statement, and the only rule to remember is that there
must be one ELSE just before the ENDIF. This sort of test waits for
an expression, and if the expression is true, then what comes after it is
executed.
About logical decisions, ugBASIC understands the following character
symbols, which are used as a form of short-hand function:

• = is used as ”equal to” (it can also be written as ==, as well);

• <> is used as “not equal to”;

• > is used as ”greater than”;;

• < is used as ”less than”;
• >= is used as ”greater than or equal to”;
• <= is used as ”less than or equal to”.

There are also three special values that can be used during the decision
making process:

• TRUE that returns 255 (-1);

95
 3 ”BASIC” concepts

• FALSE that returns 0;

• NOT that returns the logical inverse of the given value.

In all the conditional operations such as IF...THEN and REPEAT...UNTIL,

the value of -1 is used to represent TRUE, and the value of 0 is used
to represent FALSE. NOT is used to swap over every digit in a binary
number from a 0 to a 1, and vice versa. Since 255 (-1, TRUE) can
be expressed in binary as %11111111, then NOT TRUE will be equal to
FALSE, and a logical NOT operation is achieved.

3.7.5 Loops and repetitions

ugBASIC offers all of the expected programming short-cuts to allow

sections of code to be repeated as often as necessary. These repeated
parts of programs are known as ”loops”.
In particular, loops can be defined using the pair DO...LOOP, and it will
loop a list of statements forever, with DO acting as the marker position
for the LOOP to return to.
1 DO
2 COLOR BORDER YELLOW
3 COLOR BORDER BLACK
4 WAIT 500 MS
5 LOOP

The instruction EXIT forces the program to leave a loop immediately,

and it can be used to escape from all the types of loop, such as
FOR...NEXT, REPEAT...UNTIL, WHILE...WEND and DO...LOOP.
1 DO
2 COLOR BORDER YELLOW
3 WAIT 500 MS
4 COLOR BORDER BLACK
5 WAIT 500 MS
6 DO
7 COLOR BORDER RED
8 WAIT 1000 MS
9 EXIT

96
 3.7 Control structures

10 REM The border will never be green !

11 COLOR BORDER GREEN
12 WAIT 1000 MS
13 LOOP
14 LOOP

You can nest any number of loops, and when used on its own, EXIT will
”short-circuit” the innermost loop only. By including the number after
EXIT, that number of nested loops will be taken into account before
the EXIT is made.
1 DO
2 COLOR BORDER YELLOW
3 WAIT 500 MS
4 COLOR BORDER BLACK
5 WAIT 500 MS
6 DO
7 COLOR BORDER RED
8 WAIT 1000 MS
9 COLOR BORDER GREEN
10 WAIT 1000 MS
11 DO
12 COLOR BORDER RED
13 WAIT 1000 MS
14 ’ EXIT 2 = skip 1 more loop , because " EXIT " == "
EXIT 1"!
15 EXIT 2
16 REM and the second loop will be skipped
17 COLOR BORDER GREEN
18 WAIT 1000 MS
19 LOOP
20 LOOP
21 LOOP

In this way, the program will jump directly to the instruction immediately
after the relevant loop. If you need to leave a loop as a result of a specific
set of conditions, this can be made by using the EXIT IF instruction.
As explained above, in conditional operations, the value -1 (255) repre-
sents TRUE, whereas a zero represents FALSE. After using EXIT IF, an
expression is given which consists of one or more tests. The EXIT will
only be performed IF the result is found to be 255 (-1, TRUE). As with
the command EXIT, an optional number can be given to specify the
number of loops to be jumped from, otherwise only the current loop

97
 3 ”BASIC” concepts

will be aborted.
The WHILE...WEND commands provides a convenient way of making
the program repeat a group of instructions all the time a particular
condition is true.

For example, this program will show a decrement number from 10 to 1

and restart from 10 again:

1 DO
2 x = 10
3 WHILE x > 0
4 PRINT x
5 x = x - 1
6 WEND
7 LOOP

WHILE marks the start of this loop, and the condition is checked for a
value of 255 (-1, TRUE) from this starting position through to the end
position, which is marked by a WEND. The condition is then checked
again at every turn of the loop, until it is no longer true. You are,
obviously, free to use AND, OR and NOT to qualify the conditions to be
checked.

1 DO
2 x = 10
3 REPEAT
4 PRINT x
5 x = x - 1
6 UNTIL x == 0
7 LOOP

Instead of checking if a condition is true or false at the start of a

loop, REPEAT...UNTIL makes its check at the end of a loop. REPEAT
marks the start and UNTIL the end of the loop to be checked. This
means that if a condition is false at the beginning of a WHILE...WEND
structure, that loop will never be performed at all, but if it is true at the
beginning of a REPEAT...UNTIL structure, the loop will be performed
at least once.

98
 3.7 Control structures

3.7.6 Controlled loops

Control can be made much more definite than relying on whether con-
ditions are true or false. In particular, when deciding how many times a
loop is to be repeated, you can use the FOR...NEXT control structure.
For example, this sample program will print numbers from 1 to 100:
1 i = 0
2 FOR i = 1 TO 100
3 PRINT i
4 NEXT

Each FOR statement must be matched by a single NEXT, and pairs of

FOR...NEXT loops can be nested inside one another. Each loop repeats
a list of instructions for a specific number of times, governed by an index
which counts the number of times the loop is repeated. Once inside the
loop, this index can be read by the program as if it is a normal variable.
1 i = 0 : j = 0
2 FOR i = 1 TO 100
3 FOR j = 1 TO 5
4 PRINT i * j
5 NEXT
6 NEXT

Normally, the index counter is increased by 1 unit at every turn of a

FOR...NEXT loop. When the current value exceeds that of the last
number specified, the loop is terminated. STEP is used to change the
size of increase in the index value.
1 i = 0 : j = 0
2 ’ Countdown !
3 FOR i = 100 TO 1 STEP -1
4 PRINT i
5 NEXT

3.7.7 Forced jumps by expression

Jumps can be made whenever a particular variable is recognised, in

other words, regardless of any other conditions. GOTO and GOSUB are

99
 3 ”BASIC” concepts

examples of a unconditional jump. ON can be used to force the program

to jump to a pre-defined position when it recognises a specified variable
and against a choice of several positions, depending on what value is
held by the variable at the time it is spotted.

For example, this program will print repeatly the sequence ”1, 2, 3”:
1 times = 1
2 start :
3 ON times GOSUB first , second , third
4 times = times + 1
5 IF times > 3 THEN
6 times = 1
7 ENDIF
8 GOTO start
9 first :
10 PRINT 1
11 RETURN
12 second :
13 PRINT 2
14 RETURN
15 third :
16 PRINT 3
17 RETURN

The ON instruction can force a unconditional jump (GOTO) or with re-

turning (GOSUB). To work properly, the expression must have a value
from 1 up to the number of the highest possible destination. If the
expression has a value of 0 or greater than the highest possibile desti-
nation, no jump will be performed.
Take this example:
1 IF level =1 THEN GOTO level1
2 IF level =2 THEN GOTO level2
3 IF level =2 THEN GOTO level3

Can be rewritten as:

1 ON level GOTO level1 , level2 , level3

The use of an ON GOSUB structure is identical to ON...GOTO, except

that it must employ a RETURN (or a POP!) to jump back to the instruc-
tion immediately after the ON...GOSUB statement. Destinations may

100
 3.7 Control structures

be given as the name of a label, or the identification number of a line

between 1 and the maximum number of possible destinations.

3.7.8 Periodic calls

The EVERY statement is used to call up a sub-routine or a procedure

at regular intervals, without interfering with the main program. By
specifying the length of time between every call, measured in TICKS,
you can call a sub-routine.

1 colorIndex = 0
2 EVERY 50 TICKS GOSUB c h a n g e B o r d e r C o l o r
3 EVERY ON
4 HALT
5 c h ang eBor der Col or :
6 COLOR BORDER colorIndex
7 colorIndex = colorIndex + 1
8 IF colorIndex > 16 THEN
9 colorIndex = 0
10 ENDIF
11 EVERY ON
12 RETURN

Note that the sub execution time should be less than the interval time,
or the main program timings will be affected. After a sub-routine has
been entered, the EVERY system is automatically disabled. This means
that, in order to call this feature continuously, an EVERY ON command
must be inserted into a sub-routine before the final RETURN statement.
So, EVERY ON should be used before the relevant sub-routine has fin-
ished executing, while EVERY OFF is the default condition, and is used
to disable the automatic calling process altogether.

101
 3 ”BASIC” concepts

3.8 Procedures

Dividing a program into procedures makes the code more organized

and easier to read, and a procedure can be called multiple times from
different parts of the program, avoiding code duplication. Procedures
can be used to break a complex problem into simpler subproblems, that
helps to create a hierarchical structure in the program.

By breaking code into procedures, it becomes easier to understand and

maintain, and by reusing the same procedures in multiple parts of the
program, you reduce the chances of introducing errors. Finally, if you
need to change one part of the code, you can simply change the cor-
responding procedure, without having to make changes in all the parts
of the program that use that part of the code.

3.8.1 Creating a procedure

A procedure is created in exactly the same way as a normal variable, by

giving it a name. The name is prefixed by PROCEDURE keyword, then
followed by a list of parameters and the procedure itself must be ended
with an END PROC command (or END PROCEDURE, as well). PROCEDURE
and END PROC commands should be placed on their own individual lines,
but it is not mandatory.
For example:
1 PROCEDURE hello
2 PRINT " HELLO I AM A PROCEDURE !"
3 END PROC

If you try and run that program, nothing will happen. This is because a
procedure must be called up by name from inside your program before
it can do anything.
To call a procedure you need the CALL command. When the program

102
 3.8 Procedures

reaches this command, control is transferred to the first statement in

the procedure. Once all the statements in the procedure are executed,
control returns to the line after CALL.
You can also pass arguments to a procedure, enclosed in square param-
eters: arguments are values that are passed to the procedure when it is
called and that can be used within the procedure itself. If the procedure
returns a value, the calling statement just ignore it.
Now add the following line at the end of that last example, compile and
then run it.
1 PROCEDURE hello
2 PRINT " HELLO I AM A PROCEDURE !"
3 END PROC
4
5 hello []

Another way to identify a procedure is to precede it with a PROC state-

ment. Run the following example:
1 PROCEDURE hello
2 PRINT " HEY !"
3 END PROC
4
5 PROC hello
6 hello []
7 CALL hello

It is possible to place the procedure definition anywhere in your program.

When ugBASIC encounters a procedure statement, the procedure is
recognised and a jump is made to the final END PROC. In this way,
there is no risk of executing your procedure by accident.

3.8.2 Jumping in and out of a procedure

You should be familiar with the use of ON for jumping to a GOSUB

routine. It is just as simple to use this structure with procedures. In
this case, if a variable holds a particular value, a system is automatically

103
 3 ”BASIC” concepts

triggered that forces a jump to a named procedure. Of course you can

have as many values triggering off as many jumps to different procedures
as you want.
For example:
1 ON v PROC procedure1 , procedure2

Which is exactly the same as saying:

1 IF v = 1 THEN
2 procedure1 []
3 ELSE IF v = 2 THEN
4 procedure2 []
5 ENDIF

Normally, procedures will only return to the main program when the
END PROC instruction is reached. But supposing you need to jump out
of a procedure instantly. The POP PROC instruction provides you with
a fast getaway, if you ever find yourself in need of escape.
Try this:
1 PROCEDURE escape
2 FOR prison = 1 TO 1000000000
3 IF prison = 10 THEN POP PROC
4 PRINT " I AM ABANDONED ."
5 NEXT
6 END PROC

The same result can be obtained by using the EXIT PROC command,
with the difference that EXIT PROC can be extended by using an ex-
pression, in order to exit from the procedure on a specific condition:
1 PROCEDURE escape
2 FOR prison = 1 TO 1000000000
3 EXIT PROC IF prison == 10
4 PRINT " I AM ABANDONED ."
5 NEXT
6 END PROC

104
 3.8 Procedures

3.8.3 Local and global variables

To better understand the mechanisms of operation of variables within

procedures, it is necessary to understand that the procedures on ug-
BASIC are “stackless”. It means that it is possible to define a variable
local to the function, therefore invisible to the main program or to other
functions, but always visible to the function if it is called on itself, and
reinitialized.
So, all of the variables that are defined inside a procedure work com-
pletely separately from any other variables in your programs. We call
these variables ”local” to the procedure. All local variables are au-
tomatically initialized when procedure has started executing, and they
maintain their values from execution to execution. So that in the fol-
lowing example the values 1, 2 and 3 will be printed:
1 PROCEDURE plus
2 a = a + 1
3 PRINT a
4 END PROC
5
6 plus []
7 plus []
8 plus []

All the variables outside of procedures are known as “global” variables,

and they are not affected by any instructions inside a procedure. So it is
perfectly possible to have the same variable name referring to different
variables, depending on whether or not they are local or global. When
the next example is run, it can be seen that the values given to the global
variables are different to those of the local variables, even though they
have the same name. Because the global variables cannot be accessed
from inside the procedure, the procedure assigns a value of zero to them
no mater what value they are given globally.
1 a = 42
2 b = 84
3 PROCEDURE example
4 PRINT a
5 PRINT b

105
 3 ”BASIC” concepts

6 END PROC
7
8 example []

To avoid errors, you must treat procedures as separate programs with

their own sets of variables and instructions. So it is very bad practice
for the ugBASIC programmer to use the same variable names inside and
outside a procedure, because you might well be confused into believing
that completely different variables were the same, and tracking down
mistakes would become a nightmare. To make life easy, there are simple
methods to overcome such problems.

3.8.4 Parameters passing

One method is to define a list of parameters in a procedure. This

creates a group of local variables that can be loaded directly from the
main program. For example:
1 PROCEDURE hello [ name$ ]
2 PRINT " HELLO " + name$
3 END PROC
4
5 hello [" WORLD "]
6 hello [" NICE TO MEET YOU !"]

Note that the values to be loaded into name$ are entered between square
brackets as part of the procedure call. This system works equally well
with constants as well as variables, but although you are allowed to
transfer integer, real or string variables, you may transfer also arrays
using this method. If you need to enter more than one parameter, the
variables must be separated by commas, like this:
1 PROCEDURE twins [a , b ]
2 PRINT a + b
3 END PROC
4
5 PROCEDURE triplets [ x$ , y$ , z$ ]
6 PRINT x$ + y$ + z$
7 END PROC
8

106
 3.8 Procedures

9 hello [" WORLD "]

10 hello [" NICE TO MEET YOU !"]

Those procedures could be called like this:

1 twins [6 ,9]
2 triplets [" XENON " ," YAK " ," ZYGOTE "]

107
4 Texts
Imagine looking at the console of an old video game or a computer
from the 1980s. Instead of seeing detailed, colorful images, you see
only alphanumeric characters (letters, numbers, symbols) arranged in
rows and columns. This is the so called ”text mode” (or TILEMAP, in
ugBASIC jargon).
So, each character on the console (a letter, a number, a special symbol)
is represented by a numeric code. This code, usually 8 bits (hence
the name ”8-bit computer”), is stored in the computer’s memory. The
computer ”knows” that each code corresponds to a particular character,
thanks to a table called the ”character table” or ”charset” (or, again,
TILESET in ugBASIC jargon).
The console itself is divided into a grid of cells, each of which can
hold one character. The position of each character on the console is
determined by a memory address. Changing the contents of a memory
address changes the character displayed in the corresponding cell.
Although text mode is primarily ”character-based”, it is often possible
to add some color and customization. Some bits of the character code
can be used to specify the text color, background, or other attributes
such as bold or underline.

Early computers had limited memory and slow processors. Text mode
required fewer resources than graphics, allowing more information to be
displayed on a small console. Moreover, it is relatively simple to handle,
both in hardware and software. Since each character is represented by
a single code, writing and reading on the console is very fast.

109
 4 Texts

Note that not all targets have this mode. However, on systems where
only graphics mode is available, equivalent commands are available that
work in BITMAP mode.

4.1 Printing on the console

The PRINT instruction is one of the most familiar command words in

most BASIC languages. Items are printed on the console (normally all
the screen, but can be limited, see below), starting from the current
cursor position, and they may include the characters in any group of
variables or constants.
The PRINT statements can occupy their own lines, but if more than
one element to be printed is written as a single line of your program,
each element must be separated from the next by either a semi-colon
character (;) or a comma (,). An element to be printed can be a
string, a variable or a constant. Strings must be placed inside a pair of
quotation marks.

A semi-colon (;) is used to print elements immediately after one an-

other, like this:
1 PRINT " FOLLOW ";" ON "

A comma (,) moves the cursor to the next ”TAB” position on the
console, as follows:
1 PRINT " NEXT " ," TAB "

A TAB is an automatic marker that sets up a location for printing, and

is often used to lay out columns of figures, or to make indentations in
text, and setting TAB positions is explained later. Normally, the cursor
is advanced downwards by one line after every PRINT command, but
by using the semi-colon or comma at the end of the command, the
behaviour can be changed.

110
 4.2 Setting text options

Here is an example:
1 ’ " UGBASIC " and " COMPILER " are on different lines
2 PRINT " UGBASIC "
3 PRINT " COMPILER "
4
5 ’ " UG " " BAS " and " IC " are on same line
6 PRINT " UG ";
7 PRINT " BAS " ,
8 PRINT " IC "

4.2 Setting text options

The PEN command sets the colour of the text displayed on the console,
when followed by the colour of your choice. The default setting of the
pen colour is DEFAULT PEN, and alternative colours may be selected
from one of up to PEN COLORS choices, depending on the current video
mode.
For example:
1 FOR index =0 TO 15
2 PEN index
3 PRINT " PEN NUMBER "; index
4 NEXT

The PEN/PEN$ function returns a special control sequence that changes

the pen colour inside a string. This means that, whenever the string is
printed on the console, the pre-set pen colour is automatically assigned
to it. The format of the string returned by PEN/PEN$ is not specific for
the target.

Here is an example:
1 p$ = PEN$ ( WHITE ) +" WELL ALL WHITE , "
2 p$ = p$ + PEN$ ( YELLOW ) +" I STILL GOT THE YELLOW "
3 PRINT p$
4 PEN RED
5 PRINT " IN THE RED "

111
 4 Texts

To select a background colour on which your text is to be printed, you

can use the PAPER command. The command is followed by a colour
index number between up to PAPER COLORS, depending on the graphics
mode in use, in exactly the same way as PEN. The normal default colour
index number is DEFAULT PAPER.
Run the following simple example:
1 PEN DEFAULT PEN
2 FOR index = 0 TO PAPER COLORS
3 PAPER index
4 PRINT " PAPER NUMBER "; index ; SPACE (23)
5 NEXT

Similarly to the PEN/PEN$ function, PAPER/PAPER$ returns a character

string that automatically sets the background colour when the string is
printed on the console.

For example:
1 PEN BLACK
2 b$ = PAPER$ ( RED ) +" FLASH RED "+ PAPER ( BLACK ) +" THE INVISIBLE MAN "
3 PRINT b$

4.3 Positioning the text cursor

Characters are always printed at the current position of the text cursor,
and the ugBASIC programmer is offered several methods of controlling
the cursor in order to make text look more orderly, attractive or eye-
catching.
The first command is LOCATE, that moves the text cursor to the coor-
dinates of your choice, and this new location sets the start position for
all subsequent text printing until you command otherwise. All console
positions are measured in ”text coordinates”, which are measured in
units of one printed character on console, with the x-coordinate con-
trolling the horizontal position and the y-coordinate referring to the

112
 4.3 Positioning the text cursor

vertical. So, the top left-hand corner of the console has coordinates of
0,0 whereas text coordinates of 15,10 refer to a position 16 characters
from the left-hand edge of the console and 11 characters from the top.
The range of these coordinates will depend on the size of your character
set and the dimensions of the display area allocated, known as a ”con-
sole”. All coordinate measurements are taken using text coordinates
relative to the current console. To have a measure of the console size,
you can use the COLUMNS and ROWS commands. If you try and print
something outside of these limits, the console will scroll in order to have
more space.
Console are dealt with in the next section, but the current screen is
automatically treated as a console, so there is no need to define the
console to test the following examples:
1 PRINT "0 ,0": LOCATE 10 , : PRINT " STAY ON CURRENT LINE "
2 LOCATE ,5: PRINT " SIX FROM TOP "
3 LOCATE 10 ,10: PRINT " TEN DOWN AND TEN ACROSS "

Whenever you need to move the text cursor back to the top left-hand
corner of the screen in a hurry, simply tell it to go HOME and it will
automatically be relocated to coordinates 0,0 like this:
1 CLS : LOCATE 10 ,10: PRINT " MOVING ..."
2 WAIT 1000 MS : HOME : PRINT "... TO HOME !"

It is also possible to move the text cursor a pre-set distance away from
its current position, which can come in useful if you need to show speech
bubbles or shunt your text to one side temporarily. The CMOVE command
is followed by a pair of variables that represent the width and height
of the required offset, and these values are added to the current cursor
coordinates. Like LOCATE, either of the coordinates can be omitted, as
long as the comma is positioned correctly. An additional technique is
to use negative values as well as positive offsets. For example:
1 CLS : PRINT " ICELAND "
2 CMOVE 5 ,5: PRINT " SCOTLAND "
3 CMOVE , -3: PRINT " NORWAY "
4 CMOVE 10 ,14: PRINT " FRANCE "

113
 4 Texts

Characters can be printed relative to the current cursor position by

setting up a string using the CMOVE/CMOVE$ function. The following
example prints a string at coordinates 10,10 from the current text cursor:
1 a = CMOVE$ (10 ,10)
2 a = a +" UGBASIC "
3 PRINT a

You may also change the position of the text cursor directly from inside
a character string. This is ideal for positioning text once and for all
on console, no matter what happens in the program, because the text
cursor can be set during the program’s initialisation phase. The string
that is returned takes the standard format. So whenever this string is
printed, the text cursor will be moved to the text coordinates held by x
and y. For example:
1 a =" A "+ AT$ (10 ,10) +" OF "+ AT$ (2 ,4) +" STRING "+ AT$ (20 ,20) +" DIGITS "
2 PRINT a

Imagine a hiscore positioned like this:

1 score =999
2 LOCATE 12 ,10
3 PRINT " HI SCORE "; score

By using the AT/AT$ function (or the same LOCATE/LOCATE$), the score
can be moved by editing a single string, no matter how many times it
is used in the program, like this:
1 hiscore = AT$ (12 ,10) +" HI SCORE "
2 score =999
3 PRINT hiscore ; score

Programmers often need to position text in the centre of the console,

and to save you the effort of calculating the text coordinates in order
to achieve this, the CENTRE command takes a string of characters and
prints it in the middle of the line currently occupied by the cursor. For
example:
1 LOCATE 0 ,1
2 CENTRE " ABOVE "
3 CMOVE ,3
4 CENTRE " SUSPICION "

114
 4.3 Positioning the text cursor

The TAB/TAB$ function returns a special control character called ”TAB”,

which carries the ASCII code of 9. When this character is printed, the
text cursor is automatically moved to the next tabulated column setting
(tab) to the right. The default setting for this is four characters, which
can be changed using SET TAB command. This simple command spec-
ifies the number of characters that the text cursor will move to the right
when the next TAB/TAB$ is printed.
For example:
1 CLS : PRINT " HOME "
2 PRINT TAB$ ;" AND "
3 SET TAB 10
4 PRINT TAB$ ;" AWAY "

By using the CDOWN command you can force the text cursor down a
single line, like this:
1 CLS
2 PRINT " OVER "
3 CDOWN
4 PRINT " THE MOON "

The effect of summoning up the special control character exactly the

same as printing after a CDOWN command. The advantage of this al-
ternative is that several text cursor movements can be combined in a
single string, using CDOWN/CDOWN$ keyword.
For example:
1 c$ =" GOING DOWN "+ CDOWN$
2 FOR a =0 TO 20
3 PRINT c$
4 NEXT

There are also a set of other commands that move the cursor:

• CUP : move text cursor one line up;

• CRIGHT : move text cursor one character right;
• CLEFT : move text cursor one character left;

115
 4 Texts

These commands are self-explanatory, and work in exactly the same way
as CDOWN. Their equivalent functions are listed below, and work in the
same way as CDOWN/CDOWN$:

• CUP / CUP$ : return control character to move text cursor one

line up;

• CRIGHT / CRIGHT$ : return control character to move text cursor

one character right;
• CLEFT / CLEFT$ : return control character to move text cursor
one character left;

4.4 Erasing text

The CLINE command is used to clear the line currently occupied by

the text cursor. If CLINE is followed by a number, then that number
of characters get cleared, starting from the current cursor position and
leaving the cursor exactly where it is. For example:
1 CLS
2 LOCATE 0 ,1
3 PRINT " TESTING TESTING TESTING ";
4 LOCATE 0 ,3
5 PRINT " TESTING TESTING TESTING ";
6 CMOVE -7 ,
7 CLINE 7
8 LOCATE 0 ,1
9 CLINE

4.5 Tracking the text cursor

To track down the exact position of the text cursor, the following pair
of functions may be used:

116
 4.6 Defining a console

• XCURS : return the x-coordinate of the text cursor;

• YCURS :return the y-coordinate of the text cursor.

In this way, a variable is created that holds the relevant coordinate of

the cursor, in text coordinates, and these two functions may be used
independently or together. For example:
1 LOCATE 5 , 10: PRINT XCURS ; : PRINT YCURS

The MEMORIZE commands store the current position of the x or y text

cursor, so that you can print any text on the console without destroy-
ing the original cursor coordinates. These may be reloaded using the
REMEMBER command.
1 CLS
2 LOCATE 10 ,10
3 PRINT "10 ,10"
4 MEMORIZE
5 LOCATE 12 ,12
6 PRINT "12 ,12"
7 REMEMBER
8 PRINT " > REMEMBERED 1"
9 REMEMBER
10 PRINT " > REMEMBERED 2"

So you can use the REMEMBER to position the text cursor at the coor-
dinates saved by a previous MEMORIZE command. If MEMORIZE has not
been used, the relevant coordinate will automatically be set to zero.

4.6 Defining a console

Up to this point, we have spoken generically about console, making it

correspond by default to the screen. However, ugBASIC allows you to
define a limited area of the screen as the ”console”.
Once defined, this area will be the only one available to print and posi-
tion texts, and scrolling will take place only on the console thus defined.

117
 4 Texts

To define a console, use the CONSOLE command.

1 ’ create a console of 8 lines and 8 columns
2 CONSOLE 1 ,1 TO 9 , 9

Any pair of coordinates can be indicated, as long as the console is within

the screen. In other words, the sum between the abscissa and the width
of the console must be less than the width of the screen; at the same
time, the sum of the ordinate and the height of the console must be
less than the height of the screen.

As soon as the function is called, the cursor is placed in the upper left
corner. Once defined, all absolute positions (that is, those given with
the LOCATE and AT commands) will be referred to the top left corner
of the console, while the relative ones will remain so. The size of the
console can be retrieved by using the COLUMNS and ROWS instruction.
The entire size of the screen can be retrieved by using the SCREEN
COLUMNS and SCREEN ROWS.
To disable console, you can use the CONSOLE OFF command. It is
equivalent to the command
1 CONSOLE 0 , 0 TO SCREEN COLUMNS - 1 , SCREEN ROWS - 1

The ugBASIC language also allows you to define multiple consoles, each
characterized by a different constraint. Each console must be defined

118
 4.6 Defining a console

in a similar way to what has already been described, but then it must
be assigned to one of the virtual ones.
To assign a console, use the CONSOLE SAVE command:
1 CONSOLE SAVE 1

To recover a console, use the CONSOLE RESTORE or CONSOLE USE com-

mand (they are synonymous).
1 CONSOLE USE 1

Note that changing the console causes the cursor position to be saved
in the console you leave, and the cursor position to be restored in
the console you arrive at. It follows that each console has a cursor
independent of the others.

119
5 Graphics
Bitmap graphics is a way of representing a digital image by breaking
it up into a grid of small colored dots, called pixels. Each pixel has
a specific color assigned to it, and all of the pixels together form the
complete image.

Due to limited processing power and memory, 8-bit computers could

only handle relatively low resolutions. This meant that images were
made up of a limited number of pixels, often resulting in pixelated and
poorly detailed images. Color depth, or the number of colors a pixel
could represent, was very limited: typically, a palettes of 16 or 256
colors was used, offering a much narrower color gamut than modern
standards. Memory dedicated to displaying graphics was limited, too,
forcing programmers to find creative ways to manage resources and
optimize the display of images.
Despite its limitations, bitmap graphics played a fundamental role in the
development of video games and graphics applications. It stimulated
the creativity of developers, who were able to create surprisingly fun
and engaging games and programs, despite limited resources.
The ugBASIC language include commands that allows to switched be-
tween text (tiles) mode and graphics (pixel) mode. Commands that
allow you to light up a single pixel on the screen, specifying its coor-
dinates, to draw straight lines between two points, to draw rectangles
and boxes of various sizes and colors, to draw circles and ellipses, and
to choose the color of pixels, lines, and shapes.
This chapter goes into more detail about these commands.

121
 5 Graphics

5.1 Enable the bitmap mode

You can switch to bitmap mode by calling the command BITMAP ENABLE.
Given the great variety of hardware that ugBASIC supports and the iso-
morphic approach adopted, the commands to set the resolution, color
depth and other characteristics have been made as hardware indepen-
dent as possible.
It is possible to ask for specific chacteristics, such as height and width of
the screen. However ugBASIC will choose the closest resolution, based
on the hardware on which it will run. Likewise, if no type of resolution
constraint is set, the best is offered.
To change resolution and colors, you can use the following syntaxes:
1 BITMAP ENABLE ( width , height , colors )
2 BITMAP ENABLE ( width , height )
3 BITMAP ENABLE ( colors )

The width is the width requested, the height is the height requested
and, finally, the colors is the number of colors requested. If you omit
a parameters, it means that it is not important to consider.

Here you are some examples:

1 REM at least 320 x200 pixels , with 16 colors
2 BITMAP ENABLE (320 ,200 ,16)
3
4 REM at least 320 pixels of width , with 4 colors
5 BITMAP ENABLE (320 , ,4)
6
7 REM at least 256 pixels of height , with 2 colors
8 BITMAP ENABLE ( ,256 ,2)
9
10 REM at least 320 x200 pixels , with any number of colors
11 BITMAP ENABLE (320 ,200)
12
13 REM at least 320 pixels of width , with any number of colors
14 BITMAP ENABLE (320 ,)
15
16 REM it is equivalent to BITMAP ENABLE
17 BITMAP ENABLE ()
18

122
 5.2 Plot a pixel on screen

19 REM it is equivalent to BITMAP ENABLE

20 BITMAP ENABLE ( ,)
21
22 REM it is equivalent to BITMAP ENABLE
23 BITMAP ENABLE ( , ,)

Other useful commands for defining the graphics mode are HIRES and
MULTI. These are syntactic shortcuts that ask you to activate a ”high
resolution” and ”multicolor” graphics mode (whatever that might mean
to your target).

To obtain the effective width and height of the screen (canvas), you
can use SCREEN WIDTH and SCREEN HEIGHT, as well as the SCREEN
COLORS.

5.2 Plot a pixel on screen

The PLOT command is the simplest drawing command of all, and plots
a single pixel of ink colour between graphic coordinates 0,0 and SCREEN
WIDTH-1,SCREEN HEIGHT-1.

When followed by specific x,y-coordinates, the current ink colour will be

plotted at this new position. You are also allowed to omit either the x
or the y coordinate, provided the comma is left in the correct position,
and the program will draw a point on the actual x and/or y.
If an optional colour index number is added, the new colour will be used
for this and all subsequent drawing operations.
1 BITMAP ENABLE
2 CLS BLACK
3 DO
4 x = SCREEN WIDTH -1
5 y = SCREEN HEIGHT -1
6 c = SCREEN COLORS -1
7 PLOT RND ( x ) , RND ( y ) , RND ( c )
8 LOOP

123
 5 Graphics

5.3 Implicit vs explicit colors

All graphic primitives can use two conventions to represent color. The
explicit convention, which is the default, and the implicit convention.

The explicit convention is activated with the DEFINE COLOR EXPLICIT

pragma. This convention requires you to indicate the color of interest
directly on the command: you can use constants, or a numeric value (if
you know the detail of the target of interest) or even a value calculated
from the RGB components.
1 BITMAP ENABLE
2 DEFINE COLOR EXPLICIT
3 PLOT 100 , 100 , RED

The implicit convention, on the other hand, is activated with the DEFINE
COLOR IMPLICIT pragma. This convention assumes that a certain
number of colors are available: 2, 4, 16, depending on hardware lim-
its. With this convention, you will have to give the number of the
color you want to use, regardless of what the actual color associated is.
Which, obviously, will be associated with a command such as PALETTE
or COLOR.
1 DEFINE COLOR IMPLICIT
2 HIRES BLACK , WHITE
3 PLOT 100 , 100 , 1 : ’ 1 is foreground

5.4 Retrieve the color of a pixel

You can use the POINT function to find the index number of the colour
occupying your chosen coordinates, like this:
1 BITMAP ENABLE
2 PLOT 160 ,100
3 PRINT " The colour is "; POINT (160 ,100)

124
 5.5 Using the graphic cursor

This instruction can be very useful for detecting collisions, as well as

calculating the position of characters and obstacles in the game.

5.5 Using the graphic cursor

The graphics cursor sets the starting point for most drawing operations.
To establish this point, use GR LOCATE to position the graphics cursor
at your chosen coordinates.

For example:
1 BITMAP ENABLE
2 x =150 : y =10
3 FOR r =3 TO 87 STEP 3
4 GR LOCATE x , y + r
5 CIRCLE ,,r
6 NEXT

You can use the XGR and YGR to find the current coordinates of the
graphics cursor, which is the default location for future drawing opera-
tions.
For example:
1 BITMAP ENABLE
2 CLS
3 CIRCLE 100 ,100 ,50
4 PRINT XGR , YGR

5.6 Clipping the coordinates

The CLIP command is used to set an invisible rectangular boundary on

the screen, using the normal top left-hand corner to bottom right-hand
corner coordinates. All subsequent drawing operations will be clipped off
when they reach these boundaries. To toggle the command and restore

125
 5 Graphics

the normal screen display area, use CLIP and omit the coordinates.
Areas that are preserved outside of the clipped zone can be used for
items such as borders and control panels.
For example:
1 BITMAP ENABLE
2 CLS BLACK
3 CLIP 20 ,20 TO 50 ,50
4 r = ( POSITION ) 0
5 FOR r =4 TO 96 STEP 4
6 GR LOCATE 10 , r
7 ELLIPSE ,,r +9 , r
8 NEXT

5.7 Relative vs absolute coordinates

In general, when you supply coordinates with graphics commands, you

do so by supplying absolute coordinates with respect to the reference
system. However, ugBASIC also supports the possibility of supplying
coordinates relative to the current position. To do this, you must use
the ”RELATIVE” keyword. When used, the number you supply will be
added to the current coordinate.
1 BITMAP ENABLE
2 PLOT 100 , 100
3 ’ This instruction will plot a point at 102 , 98
4 PLOT RELATIVE 2 , RELATIVE -2

5.8 Drawing lines

Line drawing is extremely simple. Pick two sets of graphic coordinates,

and draw your line from one to the other. To draw a line from the
current position of the graphics cursor, use DRAW TO followed by a single
set of coordinates.

126
 5.9 Styling lines

For example:
1 BITMAP ENABLE
2 CLS
3 INK RED
4 DRAW 50 ,50 TO 250 ,150
5 DRAW TO 275 ,175

5.9 Styling lines

Changing the appearance of straight lines is very simple with ugBASIC.

Each line pattern is held in the form of a binary number made up of 16
bits, with zeros setting blank spaces in the current background colour,
and ones setting the solid parts of the pattern in the current ink colour.

So a normal solid line can be imagined as having all its bits set to one,
like this:
1 %1 111 111 111 111 1 1 1

The SET LINE command sets the style of all straight lines that are
subsequently drawn. Theoretically, the 16-bit mask can generate values
for different patterns between 0 and 65535, but here is a more practical
example:
1 BITMAP ENABLE
2 CLS
3 INK YELLOW
4 SET LINE $F0F0
5 BOX 50 ,100 TO 150 ,140
6 SET LINE % 110 0 1 1 0 0 1 1 0 0 1 1 0 0
7 BOX 60 ,110 TO 160 ,160

5.10 Selecting colors

This section explains how the ugBASIC programmer is free to exploit the
colour-handling features. Although the various targets provides different

127
 5 Graphics

colour schema and registers, ugBASIC allows the use of colour numbers
ranging from 0 to SCREEN COLORS (or COLOR COUNT).
You are not restricted to the pre-set colours that have been allocated
for drawing operations. The INK command is used to specify which
colour is to be used for subsequent drawing, and the number of the
colour is set like this:

1 CLS
2 COLOR BACK RED
3 INK YELLOW
4 DRAW TO 319 ,199

The COLOR BACK command is used to assign your choice of color for
the screen’s background colour.

5.11 Drawing connected lines

Here is a range of ugBASIC short-cuts for drawing outline shapes on

the screen. The POLYLINE is identical to DRAW except that it accepts
multiple coordinate settings at the same time.
In this way, complex many-sided outlines can be drawn with a single
statement. In its POLYLINE TO form, drawing begins at the current
graphic cursor position.
For example:

1 BITMAP ENABLE
2 CLS
3 CIRCLE 160 ,100 ,95
4 POLYLINE 160 ,6 TO 100 ,173 TO 250 ,69 _
5 TO 71 ,69 TO 222 ,173 TO 160 ,6

128
 5.12 Drawing boxes

5.12 Drawing boxes

Boxed outlines are drawn at settings determined by the top left-hand

and bottom right-hand coordinates, as in the following example:
1 BITMAP ENABLE
2 CLS
3 BOX 60 ,110 TO 160 ,160

5.13 Drawing circles and ellipses

To draw circles you can use the CIRCLE command, with a pair of coor-
dinates sets the position of the centre point around which the shape is
to be drawn, followed by the radius of the circle (the distance between
the centre point and the circumference or rim of the circle). If the
x,y-coordinates are omitted, the circle will be drawn from the current
graphic cursor position.
1 BITMAP ENABLE
2 CLS
3 INK RED
4 GR LOCATE 160 ,100
5 CIRCLE , ,45
6 WAIT 100 MS
7 DO
8 INK RND ( SCREEN COLORS )
9 x = RND ( SCREEN WIDTH /2)
10 y = RND ( SCREEN HEIGHT /2) +1
11 CIRCLE x ,y , r
12 LOOP

An ellipse is drawn in a similar way. After the x,y-coordinates have set

the centre location, two radii must be given, one to set the horizontal
width and the second to set the height of the ellipse. Coordinates may
be omitted as usual,providing the commas remain in place.
For example:
1 ELLIPSE 100 ,100 ,50 ,20
2 ELLIPSE , ,20 ,50

129
5 Graphics

5.14 Advanced topics

5.14.1 Raster graphic

On an 8-bit computer, a raster routine is a small program or sequence

of instructions that uses a particular moment in the screen display cycle
to modify the contents of the image. This is when the electron beam
(the raster beam) scans the screen, line by line, to draw the image.
Using this mechanism, programmers could create very simple, but often
surprisingly engaging, graphics, animations, and games, considering the
hardware limitations of the time.
Generally speaking, the mechanism works as follow:
• raster interrupt: the computer generated an interrupt (a signal
that stopped the program being executed) every time the raster
beam reached a certain line on the screen;
• execution of the routine: when the interrupt occurred, the pro-
cessor passed execution to the raster routine;
• modification of video state: the routine directly modified the
video memory (or registers), which contained the data that de-
fined the colors of each pixel on the screen;
• return to main program: once the change was complete, the
processor would resume execution of the main program from
where it had stopped.

Generally, 8-bit computers had limited processing power and video mem-
ory. Raster routines allowed (and allow) the computer to make the
most of the available resources, creating visual effects even on mod-
est hardware. Moreover, raster routines offered very precise control
over image generation, allowing for customized and optimized effects.
Finally, raster routines stimulated the creativity of programmers, who

130
 5.14 Advanced topics

could invent new ways to exploit this mechanism to create innovative

visual effects.
The ugBASIC language gives some instructions, like RASTER AT and
NEXT RASTER, in order to create very flexible raster routines.

131
6 Images
Bitmap image conversion is essential to the development of video games
and graphics applications on 8-bit computers. It allows images and an-
imations to be displayed in color, albeit with limitations. It also stim-
ulates the creativity of developers, who had to find ingenious solutions
to overcome the challenges posed by the hardware.
Converting bitmap images to color on 8-bit computers is, finally, a
complex process, testing the skills of algorithms and the limitations of
the hardware.
The ugBASIC language is equipped with a sophisticated image conver-
sion system, which allows the use of modern formats (like JPG or PNG)
which are then ”translated” into a native format of the target machine.

This mechanism is exposed by means of a series of primitives, which

allow you to load images and to draw them on the screen.

133
 6 Images

6.1 Loading images

To load an image from the development computer, you need to use the
LOAD IMAGE function. This function accepts, as a parameter, the name
of a file located on the development environment and it returns a value
of type IMAGE, which can then be used.

1 themill := LOAD IMAGE (" themill . png ")

The command supports a set of modern image format, like:

• JPEG baseline & progressive;

• PNG 1/2/4/8/16-bit-per-channel;

• TGA;
• BMP (non-1bpp, non-RLE);
• PSD (composited view only, no extra channels, 8/16 bit-per-

134
 6.1 Loading images

channel);
• GIF;
• HDR (radiance rgbE format);

• PIC (Softimage PIC);

• PNM (PPM and PGM binary only).

As long as it respects the limitations of the hardware, the image will

be converted into a way that can be efficiently drawn on the screen. It
could be converted, i.e., into indexed palette.

Note that the term ”load” does not imply the action performed by the
executable, but the action done by the compiler. The compiler, in fact,
will take the file, convert it into a format suitable for the target and
graphic mode, and it stores in the data segment of the program. As a
result, there is no type of access to a disk, tape or other media.

For this type of operation, ugBASIC provides other primitives, which are
covered in another chapter. Furthermore, there are obvious limitations
in the size of a single image or set of images, which cannot be overcome.
Loading the same image several times results in the generation of a
single image buffer, without repetition.
1 REM images are the very same buffer !
2 airplaneImage1 = LOAD IMAGE (" bat . png ")
3 airplaneImage2 = LOAD IMAGE (" bat . png ")

To avoid this behavior, the AS keyword must be used.

1 airplaneImage1 = LOAD IMAGE (" bat . png " AS " bat1 ")
2 airplaneImage2 = LOAD IMAGE (" bat . png " AS " bat2 ")

In order to avoid useless copies, we suggest to use the := operator:

1 airplaneImage1 := LOAD IMAGE (" bat . png " AS " bat1 ")
2 airplaneImage2 := LOAD IMAGE (" bat . png " AS " bat2 ")

135
 6 Images

Finally, on some targets it is possible to load the image onto a mem-

ory expansion, to save resident (central) memory, using the istruction
BANKED
1 airplaneImag e1 := LOAD IMAGE (" bat . png " AS " bat1 ") BANKED
2 airplaneImag e2 := LOAD IMAGE (" bat . png " AS " bat2 ") BANKED

6.2 Drawing images

The ugBASIC language offers a primitive for drawing images, and it’s
called PUT IMAGE. This primitive is designed so that it can exploit, in
the most efficient way possible, the graphics subsystem. For this reason,
although it is possible to indicate an absolute position from which to
start drawing, there is no guarantee that this position will be respected.

1 airplane := LOAD IMAGE (" a i r _ a t t a c k _ a i r p l a n e . png ")

2 PUT IMAGE airplane AT 0 ,0
3 PUT IMAGE airplane AT 16 ,16
4 PUT IMAGE airplane AT 32 ,32

For example, on many systems there is an alignment to the nearest 8

horizontal pixels (byte alignment), while on others this alignment may
also be present vertically. In general, positioning an image at (0,0) is
guaranteed to cause the image to be drawn starting from the upper left
corner.

136
 6.2 Drawing images

We began by arguing that ugBASIC converts images according to con-

textual constraints. This is implemented through the evaluation of both
which target is being compiled and the graphics mode in use at the mo-
ment. Both of these factors are evaluated at the time of compilation,
and reaffirmed at the time of execution.
In this example, we define (and, then, draw) an airplane in a bitmap
monocromatic resolution:

1 BITMAP ENABLE (2)

2 airplaneImage = LOAD IMAGE (" a i r _ a t t a c k _ a i r p l a n e . png ")
3 REM use last graphic coordinates , normally (0 ,0)
4 PUT IMAGE airplaneImage

This implies that the loading and the conversion of the images takes
place according to a graphic modality deduced from the static execution
of the code, while the drawing of the graphic elements from the dynamic
execution. This can be a bit confusing in those programs that use more
than one graphics mode.

As a general rule, the graphic elements must be defined within the

chosen resolution, and therefore it is necessary to foresee a phase in
which the program ”explores” the modalities that it will then use, in
order to define the graphic elements. Finally, remember that it is not
possible to ”mix” images defined for different graphic modes.

In this example, we define an airplane in a bitmap monocromatic res-

olution and, then, in a multicolor bitmap (we use the AS keyword to
avoid aliasing):

1 BITMAP ENABLE (2)

2 airplaneImage = LOAD IMAGE (" bat . png " AS " bat1 ")
3 BITMAP ENABLE (16)
4 airplaneImage = LOAD IMAGE (" bat . png " AS " bat2 ")

137
 6 Images

6.3 Flipping images

You can flip an image vertically, horizontally, or in both directions. The

operation can be carried out both when the image is loaded (there-
fore with a ”fixed” flip so to speak) and, on some targets, also during
execution.

The flipping at load time is done by using FLIP X, FLIP Y or FLIP XY

after the LOAD IMAGE command. At runtime, the operation is carried
out with the FLIP IMAGE command. To flip an image horizontally, use
the FLIP IMAGE X command:
1 BITMAP ENABLE (16)
2 CLS
3 boy := LOAD IMAGE (" boy . png " )
4 PUT IMAGE boy AT 0 , 0
5 FLIP XY IMAGE boy
6 PUT IMAGE boy AT 0 , 48

To flip an image vertically, use the FLIP IMAGE Y command:

1 BITMAP ENABLE (16)
2 airplaneImage = LOAD IMAGE (" boy . png ")
3 FLIP IMAGE Y airplaneImage

Finally, to simultaneously flip the image according to X and Y, you can

use the FLIP IMAGE XY (or FLIP IMAGE YX) command:
1 BITMAP ENABLE (16)
2 airplaneImage = LOAD IMAGE (" boy . png ")
3 FLIP IMAGE XY airplaneImage

138
 6.4 Loading atlas

Note that ugBASIC also accepts this other form:

1 FLIP IMAGE airplaneImage X
2 FLIP IMAGE airplaneImage Y
3 FLIP IMAGE airplaneImage XY

Finally, note that the flipping operation may not be available if the
image is BANKED, i.e. located in a virtual memory expansion, as can
happen on some targets.

6.4 Loading atlas

The ugBASIC language allows you to load an atlas (”image collection”)

in a single operation. The advantage of atlases is that they spatially
compact multiple frames into a single image, which can then be selected
when drawing an image with the PUT IMAGE command.
To read an atlas simply use the LOAD IMAGES or LOAD ATLAS com-
mand. In that case, you need to provide the size of the single frame:
1 atlas := LOAD ATLAS (" boy . png ") FRAME SIZE ( 32 , 32 )

You can use the PUT IMAGE with the following syntax:
1 PUT IMAGE atlas FRAME 2 AT 0 , 0

Note that ugBASIC does not check if the atlas has enough frames.
If you are unsure, you can use the FRAMES( ) function to obtain the
number of frames inside an atlas. Note that frames are ”0 based”, i.e.
the first frame is at 0, the second at 1, and so on. So:

139
 6 Images

1 FOR x = 0 TO FRAMES ( atlas ) -1

2 PUT IMAGE atlas FRAME x
3 NEXT x

Moreover, an animated GIF can be converted automatically in an atlas.

In this case, there is no need to give the frame size, and you can use
the FRAME SIZE AUTO syntax:
1 earth := LOAD ATLAS (" e a r t h _ 1 2 8 x 1 2 8 _ 2 c o l o r s . gif ") FRAME SIZE
AUTO

Finally, on some targets it is possible to load the atlas onto a memory

expansion, to save resident (central) memory.
1 bat := LOAD ATLAS (" bat . png ") FRAME SIZE (32 , 32) BANKED

6.5 Loading sequences

The ugBASIC language allows you to load multiple horizontal atlas

(”images strip”) in a single operation. The advantage of sequences
is that they spatially compact multiple horizontal atlas into a single
vertical stacked image, which can then be selected when drawing an
image with the PUT IMAGE command.
To read a sequence simply use the LOAD SEQUENCE command. Again,
you need to provide the size of the single frame:
1 sequence := LOAD SEQUENCE (" boy . png ") FRAME SIZE ( 32 , 32 )
2 PUT IMAGE sequence STRIP 1 FRAME 2 AT 0 , 0

Also in this case, ugBASIC does not check if the sequence has enough
atlas and frames. Note that strips and frames are ”0 based”, i.e. the
first strip is at 0, the second at 1, and so on. So:
Finally, on some targets it is possible to load the sequence onto a mem-
ory expansion, to save resident (central) memory, using the keyword
BANKED.

140
 6.6 Transparency

1 sequence := LOAD SEQUENCE (" boy . png ") FRAME SIZE ( 32 , 32 )

BANKED
2 PUT IMAGE sequence STRIP 1 FRAME 2 AT 0 , 0

6.6 Transparency

When you draw an image, you can draw it transparently.

To do this it is necessary that the original image is in a format that

maintains this information, such as the PNG or RGBA or GIF format.
In this case, ugBASIC will avoid modifying the pixel during drawing if
it is transparent. To enable this type of functionality, you need to use
the TRANSPARENCY command:
1 PUT IMAGE boy AT x , y WITH TRANSPARENCY

6.7 Getting images

With the same syntax with which images can be drawn, they can be
generated by capturing them from the visible screen. This is done with
the GET IMAGE command:
1 GET IMAGE image FROM x , y

In order to work, this command must have an image, which will receive
the graphic and color data of the image thus obtained. To obtain this
image, you can use the NEW IMAGE command.
1 dest := NEW IMAGE (16 , 16)
2 GET IMAGE dest FROM 0 , 0
3 PUT IMAGE dest AT 16 , 16

Note that, just as it is possible to create and get a single image, it is

obviously possible to generate atlases and get single frames inside it.

141
 6 Images

In this case, it is necessary to indicate the number of frames that the

atlas will have.
1 newAtlas := NEW ATLAS (10 , 16 , 16) : ’ 10 frames of 16 x16 pixel
2 GET IMAGE newAtlas FRAME 0 FROM 0 , 0
3 GET IMAGE newAtlas FRAME 1 FROM 16 , 0

6.8 Advanced topics

This section will limit itself to giving general indications on the func-
tioning of these primitives. It must in fact be taken into account that
ugBASIC is an isomorphic language, therefore it does not provide a real
abstraction but rather exposes the mechanisms of the specific target.
For this reason, it is necessary to carefully study the ”form” of the
graphic data, so that they can be used easily by all targets.

6.8.1 What is a buffer?

In order to draw an image, it is necessary to define it and, above all, to

allocate space to keep the graphic and color information. This is done
with the use of the BUFFER data type. This type of data is special: in
fact, it represents a certain memory area, of a certain size and starting
from a certain position in the memory. The ”content” of the BUFFER
is not well defined, because it depends on the target.
Defining a BUFFER is simple, because it is sufficient to use the following
syntax:
1 b = #[ aa 5 5 a a 5 5 a a5 5 a a 5 5 ]

The sequence of hexadecimal digits in square brackets describes the

contents of the buffer b. In this specific case, we are defining a memory

142
 6.8 Advanced topics

area of 8 bytes, with an alternating pattern of $55 (85 decimal) and

$aa (170 decimal) values.

6.8.2 So, what is an image?

For the purpose of image manipulation, a specific type has been in-
troduced: IMAGE. This type of data is equivalent to a BUFFER but the
content is declined according to the target and the specific graphics
mode. In other words, it is possible to define an image as a buffer is de-
fined, simply by asking ugBASIC to consider it a variable of type IMAGE,
and putting a content that is compatible with the target / chipset:
1 image = ( IMAGE ) #[10000455 aa55aa55aa55 ]

Although the actual content may vary, the format assumes that the first
two bytes represent the width (in pixels) and the third the height (in
pixels) (currently: &H0010×&H04 = 16x4 pixel), while the rest of the
sequence represents the graphic content.
Recall that ugBASIC is an isomorphic language, we have that it does
not code the content homogeneously. Each target has its own format,
and even each individual graphics mode. It follows that it is neither easy
nor advisable to manually define such information but other primitives,
much more powerful and effective, must be used.

6.8.3 Beyond transparency

While transparency is a very powerful feature for graphically represent-

ing motion and effects, sometimes you need to go further. For exam-
ple, there could be an advantage if the drawn image were first ”decon-
tourned” using appropriate masking. To do this you can take advantage
of the blitting capabilities of ugBASIC.

143
7 Blitting operations
The ”blitting” is a data operation used in computer graphics in which
several bitmaps are combined into one using a boolean (or mathemati-
cal) function.
The operation involves at least two bitmaps: a ”source” (or ”fore-
ground”) and a ”destination” (or ”background”), and other fields,
called ”masks” or something like that. The result may be written to a
final bitmap, though often it replaces the ”destination” field.
The pixels of each are combined bitwise according to the specified blit
operation (BOP) and the result is then written to the destination. The
BOP is essentially a boolean formula, that can be written in plain ug-
BASIC instructions.

The most obvious BOP overwrites the destination with the source.
Other BOPs may involve AND, OR, XOR, and other operations.
The ugBASIC language provides both a mechanism for defining BLIT
operations, data type to store them and instructions for applying them.
Moreover, instructions are designed in a general way as syntax, but
adapted according to the target of interest.

145
7 Blitting operations

7.1 A bit of history

The Commodore Amiga and its coprocessor (called ”blitter” because

of its primary operation) did something analogous to what we are ex-
plaining. With only one difference: it was not possible to express any
combination but only one of the 256 possible combinations based on
the combinatorial calculus called ”minterm” in jargon (actually there
were many less). Also, the four channels (A, B, C and D) were ”fixed”
and had given semantics, which could not be changed.
In practice: it was difficult to do something complicated (example:
thresholds), while it was quick to do something simple (example: mask-
ing). Another advantage of Commodore Amiga was that it reasoned
in ”bitplanes”, which made the blit ”sequentiable” - something that
”packed” (or ”chunked”) modes would not do. Blitting operations,
after the Commodore Amiga, became very common in 90’s PC video
cards.
For this very same reason, after the theory, we will have to deepen the
meaning of the operations in the presence of non-trivial organizations
of the bits per pixel, like VIC2, ZX ULA and so on. The granularity
of the pixel and any defects in the result due to the limitations of the
various video chips must be taken into account.

7.2 Usage

Blitting is similar to hardware-sprite drawing, in that both systems re-

produce a pattern, typically a square area, at different locations on the
screen. Hardware sprites have the advantage of being stored in separate
memory, and therefore don’t disturb the main display memory. This al-
lows them to be moved about the display, covering the ”background”,
with no effect on it.

146
 7.2 Usage

Blitting moves the same types of patterns about the screen, but does
so by writing into the same memory as the rest of the display. This
means that every time a foreground pattern is placed on the screen,
any background pixels underneath it are overwritten, or ”damaged”.
It is up to the software to repair this damage by blitting twice, once
to restore the pixels that were changed, and then again to place the
foreground pattern in its new location.
There are several ways to optimize this.
If large areas of the screen are taken over by the patterns, it may be more
efficient to blit the background to the screen instead of erasing each
pattern individually. A variation involves dividing the screen into seg-
ments and erasing only the segments where patterns have been drawn
on. This technique is known as ”dirty rectangles”.

The ugBASIC supplies you with a set of powerful BLIT IMAGE(s), GET
IMAGE and PUT IMAGE commands which allow you to grab part of an
image into memory and paste it anywhere on the screen.

These instructions are mainly used for holding temporary data, since the
images cannot be saved along with your BASIC programs. However,
the PUT IMAGE and BLIT IMAGE(s) commands can also use images
loaded from the computer, with the LOAD IMAGE, LOAD ATLAS and
LOAD SEQUENCE commands.

147
 7 Blitting operations

7.3 A preliminary example

A classic use for blitting is to render transparent sprites onto a back-

ground.

In this example a background image, a sprite, and a 1-bit mask are used.
As the mask is 1-bit, there is no possibility for partial transparency via
alpha blending.
A loop that examines each bit in the mask and copies the pixel from
the sprite only if the mask is set will be much slower than hardware that
can apply exactly the same operation to every pixel.
Instead a masked blit can be implemented with two regular BLIT oper-
ations using the AND and OR blit operations.
1 BITMAP ENABLE (16)
2 CLS BLACK

First, let’s set the graphics mode to at least 16 colors, clear the screen,
and load the various graphics resources.
1 mask := LOAD IMAGE (" examples / blit_mask . png ") EXACT
TRANSPARENCY BLACK OPACITY WHITE
2 background := LOAD IMAGE (" examples / bl it _ ba ck gr o un d . png ")
3 sprite := LOAD IMAGE (" examples / blit_sprite . png ")

When preparing the sprite, the colors are very important. The mask
pixels are 0 (black) wherever the corresponding sprite pixel is to be dis-

148
 7.3 A preliminary example

played, and other color wherever the background needs to be preserved.

On the other side, the sprite must be 0 (black) anywhere where it is
supposed to be transparent, but note that black can be used in the
non-transparent regions.

Since ugBASIC reasons in terms of the native representation, we must

use the built-in THRESHOLD operator. Alternatively, we can use the
TRANSPARENCY and OPACITY keywords on LOAD IMAGE instruction. We
will use the latter.
1 POSITIVE CONST x = ( SCREEN WIDTH - IMAGE WIDTH ( background ) )
\ #2
2 POSITIVE CONST y = ( SCREEN HEIGHT - IMAGE HEIGHT ( background )
) \ #2
3 PUT IMAGE background AT x , y

In the first blit, the mask is blitted onto the background using the blit
operator AND. Because any value ANDed with 0 equals 0, and any value

149
 7 Blitting operations

ANDed with 1 is unchanged, black areas are created where the actual
sprites will appear, while leaving the rest of the background alone.
1 BLIT bop1 AS ( ( SOURCE ) AND ( DESTINATION ) )
2 BLIT IMAGE mask AT x +10 , y +10 WITH bop1

In the second blit, the sprite is blitted onto the newly altered back-
ground using the blit operator of OR. Because any value ORed with 0 is
unchanged, the background is unaffected and the black areas are filled
with the actual sprite image. Note that we are using the ”positional”
syntax for sources.
1 BLIT bop2 AS ( ( ( INVERSE ( SOURCE 2 ) ) AND ( SOURCE 1 ) )
OR ( DESTINATION ) )
2 BLIT IMAGES sprite , mask AT x +10 , y +10 WITH bop2

It is also possible to achieve the same effect using a sprite with a white
background and a white-on-black mask. In this case, the mask would
be ORed first, and the sprite ANDed next. Finally, the very same effect

150
 7.4 A bit of theory

could be obtained by using a transparent PNG and the PUT IMAGE with
the WITH TRANSPARENCY keywords.

7.4 A bit of theory

We start to break down the process into a series of elementary steps. In

particular, the process has only two operations: unary operations and
binary operations.
Unary operations take two input parameters: the first (A) is the input
value and the second (B) is the type of operation to perform on that
input. Output (C) is output, as a result value.
The B value describes the type of operation to be performed: it ranges
from copying (COPY, C = A), to complement copying (INVERSE, C
= NOT A), to assigning a constant value (value, C = value) or,
of course, to do nothing (IGNORE, C = undefined). This last case is
useful for deactivating the specific step.

Binary operations accept one more parameter, because they operate

on the combination of two inputs: therefore A and B are the input
parameters, C the type of operation to be performed while D is the
output parameter. It is otherwise similar to the unary operation. We

151
7 Blitting operations

therefore have the possibility of performing a bitwise ”and” operation

(AND, C = A AND B, c = 0), a bitwise ”or” (OR, C = A OR B, c =
1) or a bitwise exclusive ”or” (XOR, C = A XOR B, c = 2) . Also in
this case we have the equivalent of an IGNORE command only that it
must be specified whether it is sufficient to copy the A channel or the
B channel, as it arrives.

7.4.1 How unary operations work

As anticipated, there are two types of operations that will apply to a

blit. In this post we explore operations that deal with a single input
image, the so-called unary operations.
Since we try to represent the operations with the lowest number of
bits possible, the first positions will be occupied by the possible values
according to the depth of the graphics (bpp = bit per pixel) in order to
represent a constant value. Therefore, if the first 4 bits are occupied
by possible values, we will have 5 overall bits available to represent
the operation: this means having 16 additional values, which will be
associated with different operations. A key word has been assigned to
each operation. To better represent its meaning, we will do it with
examples.

152
 7.4 A bit of theory

The simplest operation is to assign a specific color value (VALUE x, for

example the value 5). In practice, we are filling the surface with the
index of a specific color. There are as many values as the color depth
of the working graphics resolution. In this case the acceptable values
range from 0 to 15.

Immediately after we have the possibility to copy the input color (COPY).
This possibility allows you to take exactly the input image, and therefore
no specific input operations are done.

153
7 Blitting operations

The first operation we can do on the input color is to take its comple-
mentary index (INVERSE). In this case, the image that will be obtained
will be the same as input but in ”negative”. Therefore, if the input has
a value of 2 and we have 16 maximum colors, the output value will be
13.

Another interesting operation is to introduce a threshold (THRESHOLD).

With this operation, all colors other than zero (0) will assume the max-
imum available index, in this specific case 15. Note that this is an
operation that is performed dynamically, at each execution. If you want

154
 7.4 A bit of theory

to do this when loading the image, then once and for all, you can use
the TRANSPARENCY and OPACITY instructions.

Finally we have the IGNORE operation. This is a special operation, not

only because it equals to VALUE 0 but also because it indicates to the
system that this operation can be removed, perhaps for optimization.

7.4.2 How binary operations works

Now we explore operations that deal with two input images, the so-
called binary operations.

In this case the number of bits is immutable, and equals 4 bits. This
means that there is the possibility of indicating 16 different operations.

155
7 Blitting operations

A mnemonic keyword has therefore been assigned to each operation

and, to better represent its meaning, a hypothetical execution will be
shown with examples.

The most common operation is the AND (bitwise ”and”). In this type
of operation, each color bit is set to 1 only if the corresponding color
bit is equal to 1 in both images. Otherwise, the value will be zero (0).

This is followed by the OR (bitwise ”or”) operation. In this type of

operation, each color bit is set to 1 only if the corresponding color bit
is equal to 1 in at least one of the two images. Otherwise, the value
will be zero (0).

156
 7.4 A bit of theory

Finally, there is the bitwise XOR (exclusive ”or”) operation. In this type
of operation, each color bit is set to 1 only if the corresponding color
bit is different in both images. Otherwise, the value will be zero (0).

Note that this blit operation has been used on several Amstrad Games
like Sorcery, Cauldron and many others. It’s an easy way to manage
sprites, because it’s the same routine to display your sprite and to re-
move it. That’s very easy but the drawback is that your sprite is changed
by the background. The only way to prevent it is to use a specific bit
pattern in order to avoid color clash after applying the XOR operator.
There is a way to customize the blitting operator that could help in this
sense.
In addition to these three operations, there are two ”non-operations”:
operation COPY A which copies the color from the first input parameter,
ignoring the second, while operation COPY B copies the color from the
second input parameter, ignoring the first.

157
 7 Blitting operations

7.5 How to use it

After introducing the basic operations, let’s start introducing the ug-
BASIC syntax that can exploit them. We assume that operations, both
unary and binary, have parameters. The parameters are obviously the
”positional” references to the images you want to use. In turn, these
parameters are the actual images, passed as parameters. To this pur-
pose, the convention of indicating each image with the term SOURCE N
where N is precisely the image number will be introduced. The image
present on the screen (which can also be described as DESTINATION)
is conventionally associated with the value N = 0.
Let’s start by introducing the syntax to define a blitting operation:
1 BLIT name AS ( bop expression )

The name must be a global and unique identifier which will define
the blitting operation. The bop expression must instead describe
the operations to be performed between the various images (SOURCE,
SOURCE 2, DESTINATION, and so on).
To draw, the BLIT IMAGE(s) command will be used. The syntax of
this command will be identical to that of PUT IMAGE (therefore with
management of images and sequences), with two main differences. The
first is the ability to indicate multiple images (separated from each other
by a comma) and the second is to be able to indicate which blitting
operation you want to use.
1 BLIT IMAGE image AT 0 ,0 WITH name
2 BLIT IMAGE image1 , image2 AT 42 ,42 WITH name2

The simplest expression is an emulation of the classic PUT IMAGE

command:
1 BLIT putimage AS ( SOURCE )

Assuming that the image to draw has color 0 as background, we can

use this expression to draw it in transparency:

158
 7.6 Limitations

1 BLIT puttrans AS ( SOURCE OR DESTINATION )

7.6 Limitations

This technique doesn’t work, at least not directly, when used in non-
trivial graphics systems. Infact, bitwise operations on color displays do
not usually produce results that resemble the physical combination of
lights or inks. Some combinations are still used to draw interactive high-
light rectangles or region borders. When this is done to color images,
the unusual resulting colors are easily seen.
In some chipset, pixel representation is driven partly by the bitmask and
partly by the colormap, where each 8x8 pixel cell is driven by a different
set of colors. This makes blitting operations not simple. This reasoning
is valid for chipsets that have a color map, therefore it is valid for TMS
9918, MOS VIC-I, MOS VIC-II, MOS TED and not for THOMSON
EF936X, MOTOROLA 6847 and Amstrad CPC video chipset.
Staying on the MOS 6502, I’ll now move on to the GTIA (ATARI’s video
chipset), where instead there are fixed registers for each combination of
bits.

With the Motorola 6847 chipset, standard for the TRS-80 Color Com-
puter, Dragon 32 and Dragon 64 computers. It is a graphics processor
with some specific characteristics, the most important of which is the
fact that it encodes a different color for each combination of two bits.
In multicolor mode, the combinations correspond to the following col-
ors: 00 = green, 01 = yellow, 10 = blue and 11 = red. In this case
the blitting operations modify the color conspicuously. For example, 01
(yellow) AND 11 (red) equals 01 (yellow). Or, 01 (yellow) OR 10 (blue)
equals 11 (red). The final effect, when applied to images, is not very
realistic: in particular, the masking is unrecognizable.
Generally, prefer the value 1 for values other than the black value, and

159
7 Blitting operations

favor the value 0 for values similar to the black value. Obviously, we
are talking about parameters that can be indicated.
Finally, the implementation for EF936x, the chipset found in the Thom-
son MO5, MO6, TO8 and Olivetti Prodest PC128 computers, is com-
plete. On this chipset there is the possibility of programming up to 16
registers with RGB components, and this flexibility goes very well with
the management of the color indices.

160
8 Sprites
One of the biggest attractions of the console and home computer was
the ability to produce high quality games which rival those found on
genuine arcade machines. This can be done using sprites. These can
be effortlessly manoeuvred in ugBASIC, so you don’t have to be an
expert programmer in order to create your own arcade games.
Hardware sprites are not only fast, but they also take up very little
memory. So they should always be used, if present. The number of
sprites, resolution and number of colors of each sprite vary by the un-
derlying video chipset used. Normally is around 8 or 32 sprites in a
single screen, 16x16 pixel monochrome or 24x21 pixel with a maximum
number of three colors. These features don’t seem particularly impres-
sive. But there are various tricks which can increase both the numbers
and sizes of these sprites beyond recognition.
One solution is to overlap more than one sprite, in order to have more
colors (sprite compositing). Another solution is to reuse each hardware
sprite (sprite multiplexing), allowing you to apparently display dozens of
sprites on the screen at once. The resolution restriction can be exceeded
by building an object out of several individual sprites.
So you’ll be happy to discover that ugBASIC manages the entire process
automatically! Once you’ve designed your sprites with any drawing pro-
gram, you can effortlessly manipulate them with just a single ugBASIC
instruction.

161
 8 Sprites

8.1 Basic commands

Remember to have a graphic IMAGE loaded into the program when

trying out the various commands in this guide. In the examples folder
you will find out many samples. In order to load an image you can refer
to this guide.
To define an (hardware) SPRITE you need to use the SPRITE function.
It takes an image as parameter and returns a SPRITE value:
1 spriteImage = LOAD IMAGE (" sprite . png ")
2 sprite = SPRITE ( spriteImage )

The size of a sprite is the one given by the underlying hardware: so,
no adaption is done but a simple ”cropping” of the original image to
the hardware limits. In other words, if your image is 32x32 pixel large
and the underlying hardware sprite is 24x21 pixel, the image will be
”cropped” to that size.
The limits of SPRITE on various systems follows:

• c128, c64, c64reu:

– 8 sprites of 24x21 pixel with one color (SPRITE MONOCOLOR);

– 8 sprites of 12x21 pixel with three colors (SPRITE MULTICOLOR);

• coleco msx1 sc3000 sg1000
– 32 sprites of 16x16 pixel with one color

162
 8.2 Composite sprites

Anyway, from this moment on, the variable sprite will contain an iden-
tifier (”handle” in technical jargon) which will allow it to be used with
subsequent instructions. Obviously, defining a sprite does not mean
showing it on screen! It is necessary to enable (activate) it. So you
need to use the SPRITE command. This is an example:
1 SPRITE sprite ENABLE AT 50 ,100 COLOR RED

This command will display (ENABLE) a hardware sprite sprite on the

screen at the sprite coordinates 50,100 replacing the actual color with
the color RED. Note that we must not give the color explicitly, since
it is retrieved automatically by image. Moreover, the coordinates are
important and we will return to the discussion later: just think that
they do not coincide with those of the screen, and therefore a different
reference system must be used.
There is also a variant of that command, SPRITE ENABLE (also called
SPRITE ON), that allows to enable all available sprites. On the same
side, the SPRITE DISABLE (also called SPRITE OFF) command re-
moves all sprites from the screen.

8.2 Composite sprites

We said at the beginning that the characteristics of the hardware sprites

are not particularly exciting. On some chipsets it is necessary to remain
monochromatic (color and transparency) to be able to define a sprite
at maximum definition. So, how can we define a sprite with (say) 3
colors? Simple: overlapping three sprites.
To do this, we simply define three sprites and draw them all in the same
position.
1 sp rit eIm age Col o r 1 := LOAD IMAGE (" sprite_color1 . png ")
2 sp rit eIm age Col o r 2 := LOAD IMAGE (" sprite_color2 . png ")
3 sp rit eIm age Col o r 3 := LOAD IMAGE (" sprite_color3 . png ")
4 spriteColor1 = SPRITE ( s p r i t e I m a g e C o l o r 1 )

163
 8 Sprites

5 spriteColor2 = SPRITE ( s p r i t e I m a g e C o l o r 2 )
6 spriteColor3 = SPRITE ( s p r i t e I m a g e C o l o r 3 )
7 SPRITE spriteColor1 ENABLE AT 100 ,100
8 SPRITE spriteColor2 ENABLE AT 100 ,100
9 SPRITE spriteColor3 ENABLE AT 100 ,100

Of course, doing it by hand can be tedious. For this reason the ugBASIC
language allows you to define a composite sprite (CSPRITE) starting
directly from an image. What happens is that ugBASIC will separate
each individual color component from the original image, it will generate
a separate sprite for each, and then it ”hold them together” when it’s
time to move them with the SPRITE command.

1 spriteIm a g e C o l o r := LOAD IMAGE (" sprite_color . png ")

2 spriteColor = CSPRITE ( s p r i t e I m a g e C o l o r )
3 SPRITE spriteColor ENABLE AT 100 ,100

Both traditional hardware sprites and composite hardware sprites have

the same video chipset limitation, in terms of number of sprites and
resolution.

8.3 Multiplexed sprites

Although the video chipset only provides you with eight actual sprites,
it’s possible to use them to display up to 32 different objects on the
screen at once. These objects are known as multiplexed sprites and
are managed entirely by ugBASIC. Multiplexed sprites can be defined
by calling the MSPRITE function to define them, and using SPRITE as
usual.
Before you can make full use of these sprites you need to understand
some mechanism. Each hardware sprite consists of a 24x21 pixel image,
monochromatic (just one color!).

164
 8.3 Multiplexed sprites

graphics courtesy of gaymoo

Unlike hardware sprites where images are cropped, the size of a multi-
plexed sprite is taken directly from the image data, and it is rounded
to the underlying hardware size (so a 32x32 monochromatic image as
above will be converted into 4 hardware sprites of 24x21 pixels). So, if
the hardware sprites cannot be resized, a part of the area inside these
sprites is wasted, and that you need more than one sprite to represent
a large image.

As the composite sprite described above, since each hardware sprite can
draw just one color, you need a sprite for each color, too.
Finally, once the hardware sprite has been drawed on the screen, its
image can be recycled, by using another sprite image, and so on. In
this way we can have many virtual sprites.

So a multiplexed sprite is a composition of composite sprite where each

element of the composition is done by using a virtual sprite that, in
turns, use a real (hardware) sprite.
The ugBASIC language takes care of all the technical and complicated
part, leaving you with simple to use instructions, very similar to the
previous ones:
1 s p r i t e I m a g e M u l t i p l e x e d := LOAD IMAGE (" s p r i t e _ m u l t i p l e x e d . png ")
2 sp rit eMu lti ple x e d = MSPRITE ( s p r i t e I m a g e M u l t i p l e x e d )
3 SPRITE sp rit eM u l t i p l e x e d ENABLE AT 100 ,100

Due to the way multiplexed sprites are produced, there is the restriction
that you can’t have more than eight multiplexed sprites on a single

165
8 Sprites

line. In practice the system is complicated by the need to produce

sprites which are larger than the 24 pixel maximum or that have more
than one color. The ugBASIC generates these objects by automatically
positioning several multiplexed sprites ”side by side” and ”overlapped”.

So, the maximum of eight hardware sprites therefore imposes a strict

limit to the number of such objects you can display on a horizontal line.
The total width of the objects must not exceed:

• 24*8=192 pixels (for monochrome sprites)

• 24*4=96 pixels (for two colors sprites)
• 24*2=48 pixels (for four colors sprites)

• 24*1=24 pixels (for eight colors sprites)

If you try to ignore this limitation, you won’t get an error message, but
your multiplexed sprite will not be displayed on the screen. So it’s vital
to ensure that the above restriction is respected.
Normally, whenever you move a sprite, its position is updated automat-
ically during the next vertical blank period (see WAIT VBL). But if you
are moving a lot of sprites using the SPRITE command, the updates will
occur before all the sprites have been moved. This may result in a no-
ticeable jump in your movement patterns. In these circumstances, you
can turn off the automatic updating system with the DEFINE MSPRITE
ASYNC pragma. Once your sprites have been successfully moved, you
can then slide them smoothly into place with a call to MSPRITE UPDATE.
This will reposition any sprites which have moved / enabled / disabled
since your last update.

166
 8.4 Redefining sprites

8.4 Redefining sprites

The only problem with multiplexed sprites is that you never know pre-
cisely which hardware sprite is going to be used in a particular object.
This is the main reason why SPRITE/CSPRITE and MSPRITE cannot be
used together.
Normally the hardware sprites used in an object will change whenever
the object is moved. Occasionally this can be inconvenient, especially
when you are animating objects such as missiles which need to remain
visible in a wide range of possible sprite combinations.

In these circumstances, it’s useful to be able to operate on the very

same sprite, i.e. to change images. In this case, you can use a slightly
different syntax (it depends on the type of the original sprite, of course!):
1 sprite = SPRITE ( newImage , sprite )
2 sprite = CSPRITE ( newImage , sprite )
3 sprite = MSPRITE ( newImage , sprite )

This redefines immediately the graphical aspect of the sprite. Note

that, in the case of CSPRITE and MSPRITE, the images you need to use
to redefine the existing sprites must have all the same geometric and
color characteristics. For example, if you use a 32x32 pixel frame with
3 colors, you cannot replace it with a 20x20 pixel frame, nor with one
with fewer or more than 3 colors. Even in this case, no checks of any
kind are carried out: what happens is that ugBASIC will seize sprites
that are nearby, therefore giving rise to graphic defects.

8.5 Sprite palette

The colours required by a hardware sprite (SPRITE) are stored in hard-

ware registers, that can be reached in three ways:

• implied, by parsing any image;

167
8 Sprites

• indirectly, using the SPRITE COLOR instruction;

• directly, POKEing values to registers &HD027-&HD02F (c128
c64 c64reu only).

For the composite (CSPRITE) and the multiplexed (MSPRITE) sprites, it

is not possibile to act directly on the registers, and acting indirectly is
not fully supported. The more convenient way is to use image parsing.

8.6 Coordinates

In general, sprites move in a different reference system than that of the

drawable screen. To take these differences into account, without having
to write the programs as many times as there are systems equipped with
sprites, a series of constants can be used:

• SCREEN BORDER X represent the width of the border, i.e. the first
horizontal position (in sprites coordinates) where the sprite can
appear;
• SCREEN BORDER Y represent the height of the border, i.e. the
first vertical position (in sprites coordinates) where the sprite can
appear;
• SCREEN SPRITE RATIO X represent, in percentiles, what is the
relationship between the width of the screen and the width that
can be used by the sprites. If the drawable screen is 320 pixels wide
but the sprites have a horizontal precision of only 256 positions
(320/256 = 1.25), the value of the SCREEN SPRITE RATIO X
constant will be 125 (125 = 1.25 x 100);
• SCREEN SPRITE RATIO Y represent, in percentiles, what is the
relationship between the height of the screen and the height that
can be used by the sprites. If the drawable screen is 200 pixels

168
 8.6 Coordinates

wide but the sprites have a vertical precision of exactly 200 posi-
tions (200/200 = 1), the value of the SCREEN SPRITE RATIO Y
constant will be 100 (100 = 1 x 100).

169
9 I/O Controls

In the 1980s, when home computers were just starting to enter homes,
video games were a very different experience than they are today. The
mouse was a very experimental tool, and joysticks and keyboards were
the main tools for interacting with games. BASIC programming was
often the method used to create these gaming experiences.

The joystick was a simple but revolutionary device. It consisted of a lever

that could be moved in different directions and one or more buttons.
With the joystick, players could move characters on the screen more
intuitively than with the keyboard. Joysticks came in different shapes
and sizes, but the operating principle was always the same.

The keyboard, in addition to being used to type commands and pro-

grams, was also a fundamental input device for video games. It was
used to select options in menus, to enter codes, to perform specific
actions and, in some cases, even to move characters on the screen.
Joystick and keyboard, together with BASIC, represented a fundamen-
tal starting point for the development of video games. Despite the
technological limitations of the time, programmers managed to create
engaging and fun gaming experiences, laying the foundations for the
video game industry we know today.
In this chapter we illustrate how to use both of them.

171
 9 I/O Controls

9.1 Using the joystick

A joystick can be used to control movement around the screen by push-

ing its handle in the desired direction, and to trigger all sorts of actions
by pressing one or more buttons built in to its mechanism. Either of
the two (or four) joystick sockets at the back or side of your computer
will happily accept a joystick plug.
If two/four users want to control one joystick each for specially written
programs, all ports can be used.

9.1.1 Reading directions

To make a joystick interact with your programs, the computer must be

able to read its movements and actions. The ugBASIC language offers
a number of useful functions to do just that.

The JOY function inspects what is happening with the joystick and
makes a report. The maximum number of joysticks installed in the
system can be retrieved using the JOY COUNT constant.
If the joystick you are interested in is plugged into any joystick port,
the computer must be told to look at that port number. For example:
1 DO
2 j = JOY (1)
3 PRINT BIN$ (j ,5) ,j
4 LOOP

By running that routine, reports are given about the movements of the
joystick and the status of the fire-button in the form of binary numbers.
The pattern of ones and zeros in the report can then be inspected.
Binary bits shown as zero indicate that nothing is happening, whereas
if any of the bits in the report is shown as a one, it means that the
joystick has been moved in the direction that relates to that bit.

172
 9.1 Using the joystick

Here is a list of those bits along with their meanings:

In short:

• UP (0) - joystick has been moved up;

• DOWN (1) - joystick has been moved down;

• LEFT (2) - joystick has been moved left;
• RIGHT (3) - joystick has been moved right;

• FIRE (4) - fire-button has been pressed.

In ugBASIC bits can be checked in various way:

1 REM functional style
2 left = BIT ( JOY (1) , LEFT )
3 PRINT " LEFT IS : "; left
4
5 REM declarative style
6 up = BIT UP OF JOY (1)
7 PRINT " UP IS : "; up
8
9 REM conditional style
10 IF JOY (1) HAS BIT UP THEN : PRINT " UP " : ENDIF
11 IF JOY (1) IS UP THEN : PRINT " UP " : ENDIF
12
13 REM ( negative ) conditional style
14 IF JOY (1) HAS NOT BIT UP THEN : PRINT " NOT UP " : ENDIF
15 IF JOY (1) IS NOT UP THEN : PRINT " NOT UP " : ENDIF

Each of those aspects of the joystick status can also be accessed indi-
vidually, using the following functions:

• JLEFT(port) - test for joystick movement towards the left;

• JRIGHT(port) - test for joystick movement towards the right;

• JUP(port) - test for joystick movement upwards;

• JDOWN(port) - test for joystick movement downwards;
• JFIRE(port) or FIRE(port) - test for joystick fire button pressed.

173
 9 I/O Controls

Every function will returns a value of TRUE (meaning -1) if the joystick
connected to the given port number has been pushed to the directiong
requested (or the button has been pressed), otherwise a value of 0 is
returned (meaning FALSE).

These functions can be demonstrated by the following example:

1 DO
2 IF JLEFT (1) THEN PRINT " WEST "
3 IF JRIGHT (1) THEN PRINT " EAST "
4 IF JUP (1) THEN PRINT " NORTH "
5 IF JDOWN (1) THEN PRINT " SOUTH "
6 IF JFIRE (1) THEN CENTRE " BANG !"
7 LOOP

In addition to these commands, there are some very useful instructions

to implement rather frequent mechanisms. For example, to wait for the
FIRE button to be pressed on the joystick, you can use the WAIT FIRE
command.

174
 9.1 Using the joystick

9.1.2 Asynchronous vs syncronous readings

The ugBASIC language generally provides two ways to read the joystick
position.
The first, which is the most precise and timely, is the so-called syn-
chronous readings. In this case, the value of the joystick position is
read at the exact moment in which it is requested.
The advantage of this technique is that you get the instantaneous po-
sition of the joystick, and it is less demanding on the computer. The
disadvantage is that, if you are not regular in the readings, you can get
irregular movements.

On the contrary, the asynchronous readings uses the so-called ”inter-

rupts” to perform the reading. In other words, at regular intervals the
execution is interrupted and the position of the joystick at that moment
is read. The program, when it requests the joystick position, actually
gets the last known position.

The major disadvantage of this technique is that it can be demanding on

the computer, depending on the target. However, it has the undoubted
advantage of ensuring regularity in the readings over time, and so you
can get regular movements.

Both modes can be selected with a specific pragma:

• DEFINE JOYSTICK SYNC - enable the syunchronous mode (real
time readings), default for atari, atarixl, coco, coco3, d32,
d64, sc3000, sg1000, vic20, zx;
• DEFINE JOYSTICK ASYNC - enable the asynchronous mode (in-
terrupt driven readings), default for c128, c128z, c64, c64reu,
coleco, cpc, msx1;

175
 9 I/O Controls

9.2 Using the Keyboard

The keyboard can be used to interact with your routines once they are
running.
This is vital for any sort of arcade game, adventure gaming or for more
practical items such as word processing. Moreover, almost all targets
that ugBASIC supports provide a keyboard, with the obvious exception
of consoles.
For these targets, you can use the keyboard to receive typed commands,
or to use the keyboard as a very advanced and flexible joystick.
To make the code fast and optimized, the compiler provides direct
access to the underlying hardware format, which in jargon is called
”scancode”. In some targets it can coincide with the ASCII code.
However, in general, it is different from computer to computer.
For this reason it is necessary for the program to use the constants that
the language provides, and they are all prefixed by the term KEY.

9.2.1 Basic commands

The INKEY$ function checks whether the user has pressed a key, and
returns its value in a string. Note the INKEY$ command doesn’t wait
for your input in any way. If the user hasn’t entered a character, INKEY$
will simply return an empty string ””.

Example:
1 DO
2 x$ = INKEY$ : IF x$ < >"" THEN PRINT x$ ;
3 LOOP

Regardless of hardware, INKEY$ is only capable of reading keys which

176
 9.2 Using the Keyboard

return a specific 7 bit ASCII character from the keyboard. ASCII is a

standard code used to represent all the characters which can be printed
on the screen.
It’s important to realise that some keys, like the function keys o special
keys, use a rather different format: if INKEY$ detects such a key, it
could return a zero character or a non-ASCII character (ASCII code
more than 128).
You can now find the the internal scan code of this key using a separate
SCANCODE function.

SCANCODE returns the internal scancode of a key which was previously

entered using the INKEY$ function. This allows you to check for keys
which do not produce a character from the keyboard, such as F1 or
TAB. Try typing in the following small example:
1 DO
2 WHILE k$ =""
3 k$ = INKEY$
4 WEND
5 IF ASC ( k$ ) =0 THEN PRINT " You Pressed A Key With No ASCII
Code ."
6 PRINT " The scancode is "; SCANCODE
7 k$ =""
8 LOOP

To avoid having to write a loop to read a certain number of characters

with INKEY$, you can use the INPUT$ function. The function will wait
for a certain number of characters from keyboard, waiting for each one
in turn. As with INKEY$, these characters are not echoed onto the
screen. The return value is a string which will be loaded with your new
characters.

Example:
1 CLEAR KEY : PRINT " Type In Ten Characters "
2 c$ = INPUT$ (10) : PRINT " You entered "; c$

Note that this instruction is not that same as the standard INPUT com-
mand. The two instructions are completely different.

177
 9 I/O Controls

9.2.2 State of keys

The ugBASIC language provides primitives that allow you to know the
state of a single key, or multiple keys, being pressed. This is particularly
useful for implementing keyboard-controlled video games, for example
to make the character jump while moving towards the finish line.

The KEY STATE function checks if a specific button has been pressed
on the keyboard. Its parameter is the internal scancode of the key you
want to check. If this key is currently being depressed then KEY STATE
will return a value of TRUE (-1), otherwise the result will be FALSE (O).
Example:
1 DO
2 IF KEY STATE ( KEY SPACE ) = TRUE THEN PRINT " SPACE !"
3 IF KEY STATE ( KEY A ) = TRUE THEN PRINT " A !"
4 LOOP

The KEY SHIFT function returns the current status of the various con-
trol keys. These keys such as SHIFT or ALT cannot be detected using
the standard INKEY$ or SCANCODE functions. But you can easily test
for any combination of control keys with just a single call to the KEY
SHIFT function. The result is a bit map in the following format:

• LEFT SHIFT (0) - if the left SHIFT pressed;;

• RIGHT SHIFT (1) - if the right SHIFT pressed;

• CAPS LOCK (2) - if it is on or off;
• CTRL (3) - if the CTRL is pressed;

• LEFT ALT (4) - if the left ALT is pressed;

• RIGHT ALT (5) - if the right ALT is pressed;

If a bit is set to a one, then the associated button has been held down
by the user. Example:

178
 9.2 Using the Keyboard

1 CENTER " Press some control keys "

2 DO
3 LOCATE 14 , 4
4 PRINT BIN$ ( KEY SHIFT , 8)
5 LOOP

Note that not all computers support control keys, nor is it possible to
have individual pressure detection. Depending on the target, some of
the bits may not be available, or only under certain conditions.
In particular:

• atari, atarixl - only SHIFT keys are detected, and both (left
and right). The CTRL key is detected only if a key is pressed.
The CAPS LOCK detection is purely software;
• c128, c64, c64reu, c128z - both left and right SHIFT are de-
tected, separately. The CTRL key is detected. The CAPS LOCK
is equivalent to the left SHIFT;
• coco, coco3, d32, d64 - only SHIFT keys are detected, and both
(left and right);
• cpc - SHIFT keys are detected, and both (left and right), but
only on real hardware. Only the CAPS LOCK is detected;
• mo5, pc128op - only right SHIFT key is detected, and it keep
both (left and right) as pressed. The CTRL button is detected,
as well. The CAPS LOCK is not detected;
• msx1 - both left and right SHIFT are detected, as if both was
presed. The CTRL key is detected. The CAPS LOCK is detected.
• zx - no control keys are detected, yet.

To determine if keys are pressed at the same time as either or both of

the shift keys, the SCANSHIFT function returns the following values:

• NO SHIFT (0) - if no SHIFT key pressed;;

179
 9 I/O Controls

• LEFT SHIFT (1) - if the left SHIFT pressed;;

• RIGHT SHIFT (2) - if the right SHIFT pressed;
• BOTH SHIFTS (3) - if both keys pressed;

Since LEFT SHIFT and RIGHT SHIFT are bitmask, it is possible to use
the following syntaxes:
1 REM functional style
2 left = BIT ( SCANSHIFT , LEFT SHIFT )
3 PRINT " LEFT IS : "; left
4
5 REM declarative style
6 left = BIT LEFT SHIFT OF SCANSHIFT
7 PRINT " LEFT IS : "; up
8
9 REM conditional style
10 IF SCANSHIFT HAS BIT LEFT SHIFT THEN : PRINT " LEFT " : ENDIF
11 IF SCANSHIFT IS LEFT SHIFT THEN : PRINT " LEFT " : ENDIF
12
13 REM ( negative ) conditional style
14 IF SCANSHIFT HAS NOT BIT LEFT SHIFT THEN : PRINT " NOT LEFT " :
ENDIF
15 IF SCANSHIFT IS NOT LEFT SHIFT THEN : PRINT " NOT LEFT " : ENDIF

Try out the following example by pressing various keys, in combination

with the SHIFT keys:
1 DO
2 a = INKEY
3 s = SCANSHIFT
4 IF s <> 0 THEN
5 PRINT s
6 END IF
7 LOOP

The INPUT$ function loads a given number of characters into a string

variable, waiting for the user to enter each character in turn. Although
characters will not appear on the screen, similar to INKEY$, the two
instructions are totally different.
Here is an example:
1 CLEAR KEY : PRINT " PLEASE TYPE IN TEN CHARACTERS "
2 v = INPUT$ (10) : PRINT " YOU TYPED : ";

180
 9.2 Using the Keyboard

9.2.3 More input

The instruction INPUT provides you with a standard way of entering

information into one or more variables. There are two possible formals
for this instruction:
1 INPUT variable list [;]

Enters a list of variables directly from the keyboard. The var can contain
any set of variables you like, separated by commas. A question mark
will be automatically displayed at the current cursor position.
1 INPUT " Prompt "; variable list [;]
2 INPUT " Prompt " , variable list [;]

Prints out the prompt string before entering your information. Note
that you must place a semi-colon between your text and the variable
list, if you want to print out a question mark. If you use a comma, the
question mark will be not printed.
The optional semi-colon ”;” at the end of your variable list specifies
that the text cursor will not be affected by the INPUT instruction, and
will retain its original position after the data has been entered.

When you execute one of these commands, ugBASIC will wait for you
to enter the required information from the keyboard. Each variable
in your list must be matched by a single value from the user. These
values must be of the same type as your original variables, and should
be separated by commas. Here are some simple examples:
1 INPUT a : PRINT " Your number was "; a
2 INPUT " Enter a floating point number "; n
3 PRINT " You entered "; n
4 INPUT " What ’ s your name Human ?" , name$ ;
5 LOCATE 23 , : PRINT " Hello "; name$

The LINE INPUT is exactly the same as INPUT, except that it uses a
RETURN instead of a comma to separate each value you enter from the
keyboard.

181
 9 I/O Controls

Example:
1 LINE INPUT " Enter three numbers "; a , b , c
2 PRINT a , b , c

The PUT KEY command loads a string of characters directly into the
keyboard buffer, and it is most commonly used to set up defaults for
your INPUT routines. Note that end of line returns can be included
using a CHR$(13) character.
In the next example, ”NO” is assigned to the default INPUT string.
1 DO
2 PUT KEY " NO "
3 INPUT " DO YOU WANT TO CONTINUE , YES OR NO : "; a$
4 b$ = UPPER$ ( a$ )
5 IF b$ == " NO " THEN BOOM : WAIT 50 : EXIT
6 LOOP

9.2.4 Other settings

You can wait for a key press by using the WAIT KEY command. More-
over, you can also wait for releasing the keyboard, by using the WAIT
KEY RELEASE.
1 DO
2 WAIT KEY : PRINT " key pressed "
3 WAIT KEY RELEASE : PRINT " key pressed and released "
4 LOOP

Other than pragmas, you can change some parameters using the KEY
SPEED instruction. It lets you tailor the speed of the keyboard to your
own particular taste. The new speed will be used on the compiler
source. Latency is the time (in ticks or milliseconds, if MS suffix is
used) between pressing a key, and the start of the repeat sequence.
Delay is the delay between each successive character and, finally, release
is the time between the automatic release and the next press event (see
below).
Example:

182
 9.2 Using the Keyboard

1 DO
2 KEY SPEED 1000 MS , 1000 MS , 1000 MS : REM Hold down a key
for SLOW repeat
3 KEY SPEED 1 , 1 , 1: REM FAST repeat !!
4 LOOP

On some hardware, whenever you enter a character from the keyboard,

its ASCII code is placed in an area of memory known as the keyboard
buffer (or ”queue”). It is this buffer that is sampled by the INKEY$
function to get your key presses. CLEAR KEY erases this buffer com-
pletely, and returns your keyboard to its original state. It’s especially
helpful at the start of a program, as the buffer may well be full of un-
wanted information. You can also call it immediately before a WAIT
KEY command to ensure that the program waits for a fresh keypress
before preceding.
Example:
1 CLEAR KEY : REM remove current key presses
2 WAIT KEY : REM Wait for a new key

Finally, the PUT KEY command loads a string of characters directly into
the keyboard buffer. Carriage returns can be included using a CHR$(13)
(RETURN) character. The most common use of PUT KEY is to set up
defaults for your INPUT routines.

Here’s a demonstration:
1 DO
2 PUT KEY " NO "
3 INPUT " Another Game "; a$
4 IF a$ =" NO " THEN EXIT
5 LOOP

The program above assigns ”No” to the default INPUT string. Hitting
the RETURN key will enter this value straight into the variable a$.
Alternatively, you can edit the line using the normal cursor keys, and
type in your own value for a$ as required.

183
9 I/O Controls

9.2.5 Asynchronous vs syncronous readings

The ugBASIC language provides for keyboard two ways to read the keys.
The first, which is the most precise and timely, is the so-called syn-
chronous readings. In this case, the value of keyboard is read at the
exact moment in which it is requested.

The advantage of this technique is that you get the instantaneous key
pressed, and it is less demanding on the computer. The disadvantage
is that, if you are not regular in the readings, you can miss keystrokes.
On the contrary, the asynchronous readings uses the so-called ”inter-
rupts” to perform the reading. In other words, at regular intervals the
execution is interrupted and the key pressed on keyboard at that mo-
ment is read. The program, when it requests any key, actually gets the
last pressed.
The major disadvantage of this technique is that it can be demanding on
the computer, depending on the target. However, it has the undoubted
advantage of ensuring regularity in the readings over time, and so you
can avoid to lose keystrokes.
Both modes can be selected with a specific pragma:

• DEFINE KEYBOARD SYNC - enable the syunchronous mode (real

time readings) default for coco, coco3, d32, d64, mo5, pc128op,
sc3000, vic20, zx;
• DEFINE KEYBOARD ASYNC - enable the asynchronous mode (in-
terrupt driven readings), default for atari, atarixl, c128, c128z,
c64, c64reu, cpc, msx1.

184
 9.2 Using the Keyboard

9.2.6 Some theorical aspects

In general, pressing a key generates a ”key pressed” event and a ”key

released” event. The first is received when the finger presses the key all
the way down, while the second is received when the key is released.
To better represent this situation, you can draw rectangles where every
time a key is pressed, we have a rectangle:

Now, it is clear that, depending on the moment in which we check

whether the key is pressed or not, we have a more or less correct repre-
sentation of what is happening.

To better handle this situation, ugBASIC provides two different sets of

instructions.

185
9 I/O Controls

There is a set of instructions that let you know, at the moment you
check, whether a key is pressed or not, and which key that key is (or,
even, if a certain key is pressed). This type of instruction is very con-
venient for real-time video games, and are:

• WAIT KEY - wait for a key press

• KEY STATE - check if a specific key is pressed
• SCANCODE - retrieve the scan code of key pressed

• ASCIICODE - retrieve the ascii code of key pressed

• ASCIICODE - retrieve the ascii code of key pressed

On the other hand, there are also instructions that let you retrieve
the pressed key or the sequence of pressed keys, even if you are not
constantly checking the keyboard. This can be useful for those games
where the user has to type something.

• KEY PRESSED - check if a specific has been pressed

• KEYPRESS - retrieve the scan code of key pressed

186
 9.2 Using the Keyboard

• INKEY$ - retrieve the character of key pressed

• INPUT - retrieve one or more data from keyboard

Note that KEY PRESSED function will behave as an alias of KEY STATE,
unless the DEFINE KEY PRESSED ASYNC pragma option is enabled. In
order to better manage keyboard typing, ugBASIC automatically man-
ages character repetition, as described below:

This repetition occurs whenever a keyboard key is held down: in this

case, after a certain time (defined as ”latency”), a repetition of the keys
begins as if the user were continuously pressing the key. The repetition
will occur by pressing the key for a time equal to ”delay”, while the key
will be released for a time equal to ”release”.

187
10 Audio and music support

The 8-bit computers, despite their limitations in processing power and

memory, were able to produce simple sounds that enhanced the gaming
experience. Sound in 8-bit computers was generated by dedicated chips,
often integrated directly into the motherboard, and programming it was
an art that required a deep knowledge of hardware and software.
Unlike the audio sampling used today, 8-bit computers used sound syn-
thesis to ”create” sounds. This meant that sounds were generated
mathematically from parameters such as frequency, amplitude, and
waveform. Polyphony, or the ability to play multiple notes at once,
was very limited. 8-bit computers were often able to play only a few
notes at once, limiting the complexity of the music. As a direct effect,
audio quality was quite low by today’s standards. Sounds were often
simple, with few harmonics and a characteristic timbre. In addition
to musical sounds, 8-bit computers could produce a variety of sound
effects, such as explosions, gunshots, and other ambient sounds.
Programming sound in 8-bit computers required a deep understanding
of the hardware and registers of the sound chip. Programmers had
to write code in assembly or low-level language to directly control the
chip’s parameters and generate the desired sounds. Each sound chip
had a set of registers that could be written to and read by the pro-
gram to configure the sound. These registers controlled parameters
such as frequency, amplitude, volume, and waveform. To synchronize
the generation of sound with the execution of the program, an inter-
rupt mechanism was often used, to indicate that the sound parameters
needed to be updated.

189
10 Audio and music support

In ugBASIC, all the complexity is reduced by adopting specific com-

mands, which simplify and interact directly with all these aspects, while
remaining tied to the hardware characteristics of the chips.

10.1 Basic effects

Audio, notes and sound effects can be used in an ugBASIC program.

There are three common sound effects that can be called up by their
own commands, and used for testing and punctuating your routines.

By making use of the internal chipset to simulate ”white noise”, or by

sending random samples to any internal ADC, the BOOM command plays
a realistic explosive sound effect.
On many targets, or if DEFINE AUDIO ASYNC pragma is used and sup-
ported, this does not delay the program at all, so it may be necessary
to use WAIT between successive explosions, or to create specific audio
effects.

Otherwise, on other targets or if you are using the DEFINE AUDIO SYNC,
this will not happen. In any case, it is possible to give a duration (in
milliseconds) for the audio effect.
For example, there codes are equivalent:

190
 10.1 Basic effects

1 DEFINE AUDIO ASYNC

2 CENTRE " Thunderbolt and Lightning "
3 BOOM : WAIT 1000 MS : BOOM : CLS
4 CENTRE " Very Very Frightening "
5 WAIT 500 MS : BOOM
6
7 DEFINE AUDIO SYNC
8 CENTRE " Thunderbolt and Lightning "
9 BOOM 1000 MS : BOOM 500 MS : CLS
10 CENTRE " Very Very Frightening "
11 BOOM

On the other hand, the SHOOT command generates a (shorter) sound

effect in exactly the same way as BOOM.
For example:

1 DEFINE AUDIO ASYNC

2 SHOOT : WAIT 1000 MS : SHOOT : PRINT " Ouch !"
3
4 DEFINE AUDIO SYNC
5 SHOOT : WAIT 750 MS : SHOOT : PRINT " Ouch !"

191
10 Audio and music support

Unlike the built-in explosive sound effects, BELL produces a simple pure
tone. To better explain the meaning of the parameter that can be given
to the BELL command, it is essential to introduce at least a hint about
the concept of frequency, ”pitch” and note.
Every sound can be represented by a given frequency, basically an os-
cillation with a certain period. However, not all systems are capable
of generating audio at any frequency, due to many factors and limi-
tations. So there are some special frequencies that are, so to speak,
”guaranteed” (or better, approximated), and they are called ”pitch”.
Each pitch is identified by a natural number, which goes from 0 to the
maximum number of guaranteed frequencies. Only for convenience, the
frequencies linked to the ”pitch” are linked to those of the notes of a
tempered scale, that are defined for eight (8) octaves.

A temperate scale is a way to divide the various octaves of music. Each

octave is subdivided into 12 ”elementary” intervals (tempered semi-
tones) all of which have exactly the same amplitude. The amplitude of
an interval corresponds to the ratio between the fundamental frequen-
cies of the two notes (and not to the difference in frequencies). In this
way twelve semitones cover exactly the interval of one octave.

192
 10.1 Basic effects

In summary: the entire musical representation is covered by 8 octaves

of 12 semitones each, each semitone is associated with a specific pitch,
which corresponds to the guaranteed frequency, as can be seen on the
previous table. The ”pitch” of this sound can be changed by adding a
”pitch value” after the BELL command, ranging from 0 for a very deep
sound, up to higher values, for an ultra high pitched sound.
With this example it is possible to listen to the tempered scale of the
fifth octave:

1 DEFINE AUDIO ASYNC

2 FOR f =60 TO 71
3 BELL f
4 WAIT 1000 MS
5 NEXT
6
7 DEFINE AUDIO SYNC
8 FOR f =60 TO 71
9 BELL f
10 NEXT

Another way to produce sound in ugBASIC is with the use of the SOUND
command. This command can accept various parameters, depending
on the use you want to make of it.

193
 10 Audio and music support

The simplest form is to reproduce a certain frequency for a certain

duration:
1 SOUND 440 , 1000 MS : ’( reproduce a 440 Hz sound for 1 second )

Sometimes it can be useful to be able to reproduce a sound while doing

other processing. In this case, you can omit the duration and the sound
will continue until the next command or until it is stopped with the
SOUND OFF command.
1 SOUND 440
2 FOR i =0 TO 10 : PRINT " OK !": WAIT 500 MS : NEXT
3 SOUND OFF

Sometimes it can be useful to reproduce frequencies on multiple chan-

nels, or ”voices”. The SOUND command also accepts a third parameter
prefixed by the keyword ON, which is a bitmask with the mapping of the
voices.
1 SOUND 440 , 1000 MS ON %0010 ( reproduce a 440 Hz sound for 1
second on voice 1)

This additional parameter with the voice is clearly available even if you
do not indicate a duration, and this allows you to produce polyphony.
1 SOUND 440 ON %0001: SOUND 480 ON %0010
2 FOR i =0 TO 10 : PRINT " OK !": WAIT 500 MS : NEXT
3 SOUND OFF

10.2 Musical notes

The values from 0 to 107 that are used to control the pitch of the BELL
sound correspond to the notes on the keyboard of a piano. The white
key at the extreme left-hand side of the keyboard is known as ”Bottom
C”, and corresponds to pitch value 0. Value 1 is the equivalent to the
black note next to it, which is a C#, and so on up to “Middle C” at
pitch value 6, then all the way up to 107.

194
 10.3 Channels and voices

In reality, grand piano keyboards run out of notes after 88, and most
synthesizer keyboards have a lot less than that.
In Western music, notes are given their own code letter so that musicians
can all refer to the same pitch when they try and play together. These
letters repeat themselves after twelve notes, and each group of twelve
is known as an “octave”.
To indicate a specific note (of middle octave) you can use the NOTE
command, like NOTE C# or NOTE D. In order to indicate the octave,
you can use the NOTE C4 annotation. So you can use the following
command to sound a bell with A note:
1 BELL NOTE A4

10.3 Channels and voices

The retrocomputer produces sound like a river, and ugBASIC allows

you to split this river into various separate channels, all pouring out at
the same time, but each capable of individual control. These channels
can be heard individually, or mixed together, or directed to the left and
right creating stereo sound. They can also be individually increased and
decreased in volume, or dammed up altogether. Obviously, it depends
on the specific chipset capabilities if these channels can be given a
different ”voice”, and each voice can be controlled in terms of volume
and direction.
The VOLUME command controls the level of sound flowing through one
or more channels, ranging from MIN VOLUME (complete silence) up to
MAX VOLUME (ear-splitting), like this:
1 FOR level = VOLUME MIN TO VOLUME MAX
2 VOLUME level
3 BELL NOTE C4
4 WAIT 500 MS
5 NEXT

195
 10 Audio and music support

Once the VOLUME level has been set, all future sound effects and music
will be delivered at that level, across all four channels. In order to create
”stereo” effects and perfect sound mixes, each of the voices needs to
be adjusted independently from one another.

The volume of each voice can now be controlled by specifying voices

and volumes, like this:
1 VOLUME 63 ON %0001
2 BOOM : WAIT 100 MS
3 VOLUME 5 ON %1110
4 BOOM : WAIT 50 MS
5 BELL 40 : WAIT 50
6 VOLUME 60: BELL 40

10.4 Playing notes

Patterns of individual notes can be played, allocated to any voice, given

a pitch and delayed for pause, using just one PLAY command:
1 PLAY voice , note , delay

The voice parameter is optional, allowing notes to be played through

any combination of the retrocomputer voices, and is set by the usual
bitmap format. The note parameter uses the values from 0 to 107, or
by using the NOTE annotation. The parameter delay sets the length of
any pause between this PLAY command and the next instruction in the
program, with a value of zero starting the note and immediately going
on to the next command.

The next example demonstrates this technique, including stereo har-

monies:
1 PLAY 40 , 0 ON 1: PLAY 50 , 0 ON 2
2 WAIT KEY
3 PLAY 50 , 15 ON 1: PLAY 50 , 15 ON 2
4 DO
5 v = RND (5)
6 p = RND (108)

196
 10.5 Instruments

7 PLAY p , 3 ON v
8 LOOP

PLAY is not restricted to pure notes. It is possible to assign complex

wave forms to voices, using the WAVE and NOISE commands, which are
explained next. To stop the playing process, simply turn it off like this:
1 PLAY OFF

Finally, the PLAY comamnd allows you to use a string with a specific
syntax to describe notes, duration, volume, and other musical parame-
ters.

Musical notes can be specified using the letters A through G, with

numbers to indicate the octave, or a number from 1 to 9. The duration
of a note can be specified with the letter L. To insert a rest, use the
letter P. The octave can be specified with the letter O followed by a
number. The tempo of the song can be changed with the T command,
while the volume can be changed using the V letter.
1 PLAY " O1V31T2L4GGL8GGL4B - AAGGF + G "

10.5 Instruments

Some audio chipsets have the ability to define the waveform of the
sound that will be output, to make it look like an instrument. Others
have the ability to use actual ”samples”, which will then be reproduced
at certain frequencies.

The ugBASIC language provides a set of primitives that allow you to

take advantage of this feature, if present.
The most useful (and easy) command is INSTRUMENT. This command
allows you to modify the waveform of one of the voices, so that subse-
quent commands such as SOUND or PLAY modify the sound.

197
 10 Audio and music support

The syntax is quite easy:

1 INSTRUMENT $42 ON %0001 : ’ Use the saxophone on voice 1

The instrument can also be indicated symbolically.

10.6 Playing music

The ugBASIC music system allows soundtracks in background to be

added to any program. Music can be created from a variety of sources,
including MIDI and PSG files.

10.6.1 Play MIDI soundtracks

The ugBASIC language is able to use directly the MIDI file format. This
kind of file is converted into internal format (called IMF - Isomorphic
Music Format), that is a format that the hardware is able to use almost
directly. So, actually, the file inside the executable is IMF format and
not MIDI.
MIDI files can be loaded using the LOAD MUSIC command:
1 soundtrack := LOAD MUSIC (" some . mid ")

Once load, they can be played anytime using the MUSIC command:
1 MUSIC soundtrack

The volume is controlled by MUSIC VOLUME, and speed (used during

conversion) by MUSIC TEMPO. Individual music passages can be sus-
pended by using the MUSIC PAUSE, and resumed by MUSIC RESUME.
Moreover, it can be stopeed by MUSIC STOP instruction.

198
 10.6 Playing music

10.6.2 Play SJ2 soundtracks

The ugBASIC language is able to load the SJ2 files. The format consists
of a 1-bit sample stream of samples for two independent voices, which
can be played synchronously with the 1-bit DAC. The player is based
on the highly optimized algorithm called ”2 voice squarewave pattern”,
developed by Simon ”invisibleman” Jonassen and adapted for ugBASIC.
The audio card is properly emulated by the latest version of XRoar
emulator.

The file can be loaded as:

1 soundtrack := LOAD (" some . sj2 ")

Once loaded, they can be played anytime using the MUSIC ... SJ2
command:
1 MUSIC soundtrack SJ2

Since they are played synchronously, the tracks can’t be suspended,

resumed or stopped.

10.6.3 Play PSG soundtracks

The ugBASIC language is able to load the PSG files with the target
that has a SN-76489 audio chipset. For TRS-80 Color Computer 1/2
and 3 it means that a Game Master Cartridge should be attached to
slot 0. The audio card is properly emulated by the latest version of
XRoar emulator. For Olivetti Prodest PC128 it means that an external
soundcard should be attached, like the one built by Dino Florenzi. The
audio card is properly emulated by the latest version of DC MOTO
emulator.
The file can be loaded as:
1 soundtrack := LOAD (" some . psg ")

199
 10 Audio and music support

Once loaded, they can be played anytime using the MUSIC ... PSG
command:
1 MUSIC soundtrack PSG

Individual music tracks can be suspended by using the MUSIC PAUSE,

and resumed by MUSIC RESUME. Moreover, it can be stopeed by MUSIC
STOP instruction.

200
11 Expansion memory

Home computers and console were limited by their 8-bit architecture,

specifically the amount of memory that could be directly addressed by
the CPU. Most used a 16-bit address bus, limiting the amount of directly
accessible memory to 64KB (216 bytes). Many applications, especially
games and more complex software, required more memory than was
provided by default. To overcome these limitations, several techniques
were developed:
The first is to divide the memory in banks, each of which could be
mapped to different areas of the memory address. With the use of
special circuits, the programmer could ”switch” memory banks, making
larger portions of memory accessible. The software was responsible for
managing the switching of memory banks, providing transparent access
to memory.
The second is to use the so called DMA (Direct Memory Access). This
allowed external devices, such as sound or video cards, to directly access
system memory, bypassing the CPU. DMA freed the CPU from repet-
itive tasks, such as transferring large blocks of data, improving overall
system performance.
In this chapter we will introduce the concept of ”expansion memory” as
given by ugBASIC, as well as all the features that the language makes
available to mitigate memory limitations.

201
11 Expansion memory

11.1 Banked expansion memory

11.1.1 How it works

Let’s take the simplest case, even if perhaps a little useless.

We have an image and we want to store it in expanded memory. And
when we need it, we want to be able to draw it on the screen.

Then, ugBASIC will store the image on expanded memory (with the
LOAD IMAGE command). When it’s time to draw it on the screen, just
use the PUT IMAGE command.

Behind the scenes, ugBASIC will take the image from the expanded
memory and copy it, reading it from the bank, into the resident memory.
At this point it will use the data copied in the resident memory to draw
on the screen.

202
 11.1 Banked expansion memory

If you ask to draw the same image again, since the graph data has
already been copied from extended memory, it will not be copied again.
The previous one will be used. And again, and again, whenever you
draw that image.

11.1.2 Shared resident memory

Clearly, you may have more than one image to draw. For example,
suppose you have two and want to draw them. The mechanism will be
similar to the previous one.

203
11 Expansion memory

The key difference in this case is that you are drawing two different
images. In this case, ugBASIC will not be able to refrain from copying
the graphic image from the expanded memory again, even during the
second call.
Note that a certain amount of resident memory is reserved to implement
this mechanism. The memory needed is the one needed to host the
largest IMAGE or the largest frame of any ATLAS and SEQUENCE.

11.1.3 Multiple shared resident memory

204
 11.1 Banked expansion memory

Is is possible to avoid copying the graphic resource every time, having

multiple resident memory areas. In that case, the behavior changes
again because ugBASIC will be able to avoid copying a given resource
that has already been copied previously.

However, attention must be paid to the fact that, for each area ded-
icated to copying, a certain amount of resident memory will be lost.
Also, as we explained in the previous section, the required resident
memory area will be sized with the largest of the blocks that can be
copied from the expanded memory. It goes without saying, therefore,
that it is advisable to combine blocks of memory of similar length in a
single sharing space.
Clearly, what is the best strategy between having memory resident zones
and shared zones is the full responsibility of the developer.

11.1.4 Loading resource

To load a resource into an expanded memory bank, and then to use a

single shared space, the BANKED keyword must be used. This command
tells ugBASIC that the resource should be stored in expanded memory,
and retrieved from there if needed.
1 player := LOAD IMAGE (" player . png ") BANKED

This command will load the player image into expanded memory and
associate it with the player variable. Notice how we are using the
direct assignment syntax (:=). This is needed because, otherwise, the
resource will be placed in expanded memory but what will be assigned to
the player variable will be a... copy! So we will take up both expanded
and extended memory, to no avail.
Of course, we can use the variable as we did before, without any par-
ticular restrictions:
1 PUT IMAGE player AT 40 , 40

205
 11 Expansion memory

11.1.5 Loading resource on separate shared memory

To load multiple resource into an expanded memory bank, and then

to use different shared space for each, the BANKED keyword must be
followed by the number of the shared memory. You can have up to 256
different resident memories.

Example:
1 CONST pShared = 1
2 CONST aShared = 2
3 p1 := LOAD IMAGE (" p_idle . png ") BANKED ( pShared )
4 p2 := LOAD IMAGE (" p_run . png ") BANKED ( pShared )
5 a1 := LOAD IMAGE (" a_idle . png ") BANKED ( aShared )
6 a2 := LOAD IMAGE (" p_run . png ") BANKED ( aShared )

Of course, we can use the various variables as we did before, without

any particular restrictions:
1 PUT IMAGE p1 AT 40 , 40
2 PUT IMAGE a1 AT 0 , 0

11.1.6 Defining arrays on expansion memory

In addition to graphics resources, entire arrays can also be moved to

the memory expansion. The advantage, in this case, is that it does not
occupy precious resident memory: with each access, whether reading
or writing, the data will be updated on the memory expansion, with
minimal occupation of the resident memory.
To define an array on expanded memory simply use the DIM instruction
and write:
1 DIM la (100 , 100) AS INTEGER BANKED

Read and write access is the same:

1 x = la ( 42 , 42 )
2 la ( 42 , 42 ) = 21

206
 11.2 DMA expanded memory

If you want to avoid accessing the elements of an array with indices,

and work with pre-calculated offsets, then you need to use the BANK
READ and BANK WRITE instructions.
1 offset = 42 * 100 + 42
2 laAddress = VARBANKPTR ( la ) + offset
3 BANK READ VARBANK ( la ) FROM la TO VARPTR ( x ) SIZE 2
4 BANK WRITE VARBANK ( la ) FROM VARPTR ( x ) TO laAddress SIZE 2

Note that, in the case of variables that are recipients of the BANK READ
or BANK WRITE command, it is necessary to characterize the array with
the appropriate flag.
1 DIM y (42 ,42) FOR BANK READ
2 BANK READ VARBANK ( la ) FROM laAddress TO VARPTR ( y ) SIZE 2

11.2 DMA expanded memory

Let’s take the simplest case. We have an image and we want to store
it in expanded memory. And when we need it, we want to be able to
draw it on the screen.

ugBASIC will store the image on expanded memory (with the LOAD
IMAGE command). When it’s time to draw it on the screen, just use
the PUT IMAGE command. Behind the scenes, ugBASIC will take the

207
 11 Expansion memory

image from the expanded memory and copy it directly into the video
memory, to draw on the screen.

11.2.1 Loading resource on expansion

To load a resource into an expanded memory bank, the BANKED keyword

must be used. This command tells ugBASIC that the resource should
be stored in expanded memory, and retrieved from there if needed.
1 player := LOAD IMAGE (" player . png ") BANKED

This command will load the player image into expanded memory and
associate it with the player variable. Notice how we are using the
direct assignment syntax (:=). This is needed because, otherwise, the
resource will be placed in expanded memory but what will be assigned to
the player variable will be a... copy! So we will take up both expanded
and extended memory, to no avail.

Of course, we can use the variable as we did before, without any par-
ticular restrictions:
1 PUT IMAGE player AT 40 , 40

11.2.2 Defining arrays on expansion memory

In addition to graphics resources, entire arrays can also be moved to

the memory expansion. The advantage, in this case, is that it does not
occupy precious resident memory: with each access, whether reading
or writing, the data will be updated on the memory expansion, with
minimal occupation of the resident memory.
To define an array on expanded memory simply use the DIM instruction
and write:
1 DIM la (100 , 100) AS INTEGER BANKED

208
 11.2 DMA expanded memory

Read and write access is the same:

1 x = la ( 42 , 42 )
2 la ( 42 , 42 ) = 21

If you want to avoid accessing the elements of an array with indices,

and work with pre-calculated offsets, then you need to use the BANK
READ and BANK WRITE instructions.
1 x = la ( 42 , 42 )
2 la ( 42 , 42 ) = 21

1 offset = 42 * 100 + 42
2 laAddress = VARBANKPTR ( la ) + offset
3 BANK READ VARBANK ( la ) FROM la TO VARPTR ( x ) SIZE 2
4 BANK WRITE VARBANK ( la ) FROM VARPTR ( x ) TO laAddress SIZE 2

209
12 Mass storage support
8-bit computers, despite their simplicity compared to modern PCs, were
capable of performing surprisingly complex tasks. A key role in this
versatility was played by mass storage devices, devices that allowed
data to be stored permanently, in addition to volatile RAM.

A mass storage device is a hardware device that can store large amounts
of data nonvolatilely, that is, so that the data remains stored even when
the computer is turned off. In 8-bit computers, the most common types
of mass storage devices were cassettes (used magnetic tape to record
data) and floppy disks (flexible magnetic disks encased in a plastic case).

To use a mass storage device, the computer had to have a special

drive (reader). The ugBASIC program, using specific instructions, could
communicate with the drive to read or write data to the storage medium.
It offers a set of commands for interacting with mass storage devices.
Moreover, some specific commands allow you to automatically arrange
the media based on the programmer’s needs.

12.1 Loading a string

In ugBASIC you can take advantage of specific instructions, which allow

you to define the contents of the storage media. These instructions
have the dual purpose of indicating the position of the assets (graphics,
sound, data) and of connecting them to specific areas of memory, where
they will be loaded during the game.

211
 12 Mass storage support

The following example shows how to define a media that will have, in
addition to the executable, also a data file with the some text.
1 CLS
2
3 STORAGE " DISCHETTO " AS " DISK1 "
4 FILE " test . txt " AS " test . dat "
5 ENDSTORAGE
6
7 DIM textRuntime AS STRING
8
9 textRuntime = " "
10
11 DLOAD " test . dat " TO STRPTR ( textRuntime ) SIZE 16
12
13 INK WHITE
14 PRINT textRuntime

After clearing the screen, the definition of the media begins.

The first instruction is BEGIN STORAGE, which allows you to begin de-
scribing the content of the media. There are two parameters that are
given. The first is a symbolic name, which can be used to distinguish
multiple media. The second, optional, is the name of the file that will
contain the image that will be created. If omitted, the name will be
assigned automatically based on program’s name, and incrementally.
It follows the definition of the data that will be put inside this specific
storage. The syntax will be the same as the LOAD commands. The
main difference is that is possible to give it a name. This will help
the programmer to find out the file, and to load it. Currently, we are
using the FILE statement, since it is a generic data file, not related to
a specific resource.
The ENDSTORAGE closes the definition.

Now the program stats. After defining a string large enough to store the
data, we are giving the address of the string to the DLOAD command.
The relative space is allocated in the previous line, so it can be used to
store the data from the file.
Finally, we print out the string.

212
 12.2 Loading an image

12.2 Loading an image

The following example shows how to define a media that will have, in
addition to the executable, also a data file with the image of a red
token:

1 BITMAP ENABLE
2
3 STORAGE " disco " AS " disk1 "
4 IMAGE " token_red . png " AS " tokenred "
5 ENDSTORAGE
6
7 CLS
8 tokenImage := NEW IMAGE (16 , 16)
9 DLOAD " tokenred " TO VARPTR ( tokenImage )
10 PUT IMAGE tokenImage AT 32 , 32

As you can see, the first instruction activates the graphics mode. This
is a precondition because ugBASIC will have to encode the image, in
order to insert it on the media.

At this point the definition of the media begins.

The first instruction is BEGIN STORAGE, which allows you to begin de-
scribing the content of the media. It follows the definition of the data
that will be put inside this specific storage. The syntax will be the same
as the LOAD commands. The main difference is that is possible to give
it a name. This will help the programmer to find out the file, and to
load it. The ENDSTORAGE closes the definition.
Now the program stats. After clearing the screen, a space for the new
image will be allocated inside the program with the NEW IMAGE instruc-
tion. So, it can be load from the storage using the DLOAD command.
Note how we are giving the address of the image to the DLOAD com-
mand. The relative space is already allocated, so it can be used to
retrieve the data from the file. No need to give the size of the data to
be read, since it is implicitly calculated by ugBASIC.

213
 12 Mass storage support

12.3 Loading an atlas

The following example shows how to define a media that will have, in
addition to the executable, also a data file with an atlas.
1 BITMAP ENABLE (16)
2
3 STORAGE " disco " AS " disk1 "
4 IMAGES " bat . png " AS " bat " FRAME SIZE (32 , 32)
5 ENDSTORAGE
6
7 CLS
8 batImages := NEW IMAGES (10 , 32 , 32)
9 DLOAD " bat " TO VARPTR ( batImages )
10
11 DO
12 PUT IMAGE batImages FRAME frame AT 0 , 0
13 ADD frame , 1 , 0 TO FRAMES ( batImages ) -1
14 LOOP

214
13 Multitasking

Imagine a 8-bit home computer or console that must do more thing

at once, from reading the joystick to write to the video memory. This
computer, as powerful as it is, has only one central processing unit
(CPU). So how can it do multiple tasks at once?
The answer is multitasking.
It’s like when you cook: while the water for the pasta is boiling, you
can make the sauce. You don’t do both at the same time, but you
switch between the tasks so quickly that they seem to be happening
simultaneously.
To implement multitasking, especially on 8-bit computer with limited
resources, a very effective technique is that of ”protothreads”. Think
of a protothread as a small state machine: it has a start state, a set of
actions to perform, and a final state. The computer switches between
the protothreads, executing a few instructions from each protothread
every cycle.
They don’t require a complex operating system or sophisticated memory
management system, and they are optimized to execute a few instruc-
tions per pass, minimizing overhead.
In ugBASIC they are also relatively easy to use: in this chapter you will
learn how you can write multitasking programs using parallel program-
ming, available “out of the box” on ugBASIC.

215
 13 Multitasking

13.1 Defining parallel procedures

In ugBASIC the PROCEDUREs are stack less. This means that there is
no stack for local variables, but they are mapped (trasparently) into the
memory.
This means that standard PROCEDUREs are ready to be promoted for a
parallel approach. And in fact converting a sequential procedure into a
parallel one is very simple: just add the PARALLEL keyword where you
use the PROCEDURE keyword.
For example, this procedure will print forever the string “example” on
the screen:
1 PROCEDURE example1
2 DO
3 PRINT " example "
4 LOOP
5 END PROC

So you can call it using the standard syntax:

1 example1 []

If you want to convert this routine in a procedure that can be run in a

multitasking fashion, you have to use the PARALLEL keyword, like that:
1 PARALLEL PROCEDURE example1
2 DO
3 PRINT " example "
4 LOOP
5 END PROC

When this keyword is added, the procedure can no longer be called

directly from the program but the keyword SPAWN must be used. So:
1 SPAWN example

216
 13.2 Deciding the right moment

13.2 Deciding the right moment

The SPAWN command will prepare only the system to run the procedure
in a parallel fashion. You need to decide when this will occour in your
main program.
Now let’s try to write down the following example program, and run it.
1 PARALLEL PROCEDURE example
2 DO
3 PRINT " example "
4 LOOP
5 END PROC
6
7 SPAWN example

If you compile the source code you can notice that serveral ”exam-
ple” strings will be printed on the screen. This happens since the RUN
PARALLEL is implicitly called by ugBASIC at the end of the main pro-
gram, and you did not call RUN PARALLEL in your source.
The RUN PARALLEL command is needed to invoke a ”multitasking slice”.
Whenever that command is invoked, all the procedures registered to run
in parallel mode are executed in the same ”slice” of time. In order to
make ”permanent” execution of the various programs in parallel, you
need to place the call inside a DO...LOOP.
For example, this is a very simple example. We will run two separates
tasks: the first will print the ”example” string, while the second will
print the ”example2” string. Since the two tasks are running at the very
same time on the processor, the two strings are printed alternatively.
But each print of both will wait for a key press.
1 PARALLEL PROCEDURE example1
2 DO
3 PRINT " example "
4 LOOP
5 END PROC
6
7 PARALLEL PROCEDURE example2
8 DO

217
 13 Multitasking

9 PRINT " example2 "

10 LOOP
11 END PROC
12
13 SPAWN example1
14 SPAWN example2
15
16 DO
17 RUN PARALLEL
18 WAIT KEY
19 LOOP

13.3 Simple synchronization

Now let’s introduce a way to synchronize the execution of two tasks.

In particular, this is the way to invoke a task inside another task, and
how to wait the end of execution of the inner task before continue.
1 PARALLEL PROCEDURE example1
2 FOR x = 1 TO 10
3 PRINT " example "; x
4 NEXT
5 END PROC
6
7 PARALLEL PROCEDURE example2
8 WAIT PARALLEL SPAWN example1
9 PRINT " example2 "
10 END PROC
11
12 SPAWN example2
13
14 DO
15 RUN PARALLEL
16 LOOP

As you can easily verify by running this program, the second procedure
will execute only when the first has finished. In order to wait the execu-
tion, we will use the WAIT PARALLEL instruction. This command will
take the identification of the current task (“task id”), that is the valure
returned by the SPAWN command.

218
 13.4 Kill a thread

13.4 Kill a thread

Once a thread has been started, it can be stopped at any time using the
KILL command. This command takes a thread ID, and stops it. Once
stopped, it can be restarted again using the SPAWN command again.
1 PARALLEL PROCEDURE example1
2 DO
3 PRINT " example "
4 LOOP
5 END PROC
6
7 t1 = SPAWN example1
8
9 PARALLEL PROCEDURE example2
10 SHARED t1
11 i = 0
12 DO
13 PRINT " example2 "
14 INC i
15 IF i = 10 THEN
16 KILL t1
17 ELSEIF i = 20 THEN
18 t1 = SPAWN example1
19 i = 0
20 ENDIF
21 LOOP
22 END PROC
23
24 SPAWN example2
25
26 DO
27 RUN PARALLEL
28 LOOP

13.5 Using (local) variables

As we said earlier, procedures do not have an independent stack. This

means that it is not possible to use local variables, at least not directly.
More precisely, each variable is shared among all tasks (of the same
type).
1 PARALLEL PROCEDURE example

219
 13 Multitasking

2 DO
3 x = x + 1
4 PRINT x ;" ";
5 LOOP
6 END PROC

In this example, the x variable is shared among all invoked tasks. So,
if you invoke 5 tasks, the value of x will be increased monotonously as
well as if you invoke just one task.

To overcome this problem you can use just a global array (x(...)),
the size of which will be equal to the number of tasks concurrently in
execution. Each element of the x array will store the variable value for
that specific task. To find out what is the number of the task being
executed is, you can use the keyword TASK (or THREAD).

Let’s look at this example:

1 DIM x WITH 0 (3)
2 GLOBAL x
3
4 PARALLEL PROCEDURE example
5 DO
6 x ( TASK ) = x ( TASK ) + 1
7 PRINT x ( TASK ) ;" ";
8 LOOP
9 END PROC
10
11 SPAWN example
12 SPAWN example
13 SPAWN example

When running the example, you will see that the value of x will be
incremented, separately, for each task.
Finally, you can use a shorter form by enclosing the variable name inside
square brackets:
1 ’ [ a ] -> a ( TASK )
2 PARALLEL PROCEDURE example
3 DO
4 [x] = [x] + 1
5 PRINT [ x ];" ";
6 LOOP
7 END PROC

220
 13.6 Enable and disable

13.6 Enable and disable

In some situations, it is necessary to ensure that a sequence of opera-

tions is executed atomically, without interruption. The FORBID instruc-
tion plays a crucial role in this way, offering the programmer a way to
take full control of the system’s execution, at least temporarily.
In simple terms, FORBID blocks any attempt by ugBASIC to pass exe-
cution from one task to another. This means that the task that called
FORBID will continue to execute its code without interruption until a
corresponding call to ALLOW is made. The FORBID ensures that a se-
quence of critical operations is executed indivisibly, without interference
from other tasks. This gives the programmer granular control over the
system’s execution.
So, if a task needs to access a shared resource (such as a global variable
or hardware device) exclusively, it can call FORBID before accessing the
resource and ALLOW after releasing it. This prevents other tasks from
modifying the resource at the same time. In some cases, disabling mul-
titasking can improve system performance by eliminating the overhead
of other task execution.

221
14 Assembly
The 8-bit computer era was a fascinating time for computing, charac-
terized by a close relationship between hardware and software. In this
context, two programming language played a fundamental role, and
they were BASIC and, above all, assembly.
Assembly is the low-level language that works directly with the processor
architecture. Each instruction corresponds to a single instruction of
the machine processor, offering granular control over the hardware and
allowing to optimize performance to the maximum.
The integration between the two languages represented a significant
step forward in programming for 8-bit computers because it allowed
to exploit the advantages of both languages. And so allows ugBASIC,
which provides a rapid and intuitive development environment, ideal for
prototyping and developing basic applications. With assembly, you can
optimize the critical portions of the code, such as graphics routines or
intensive mathematical operations, obtaining high performance. Finally,
assembly allows you to interact directly with the computer’s peripherals,
such as graphics, sound, and I/O ports, offering an unparalleled level of
control.

223
 14 Assembly

14.1 Loading object code

The ugBASIC language provides a command to load binaries, the LOAD

command, and this is a way to interface with code written in assembly
or with pre-existing libraries. For example, suppose we have a program
compiled in machine language, which is completely relocatable. To be
able to load it into your ugBASIC program, simply enter the following
command:
1 executable := LOAD (" executa ble_nop . bin ")

Assuming that the first instruction matches the starting address of the
file, it is sufficient to retrieve the address of that variable and use it.
To do this you have the command VARPTR available. This command
returns the address of the given variable:
1 address = VARPTR ( executable )

Finally, it is necessary to introduce a command that calls the loaded

code. The command is the SYS command (or EXEC, which is a syn-
onym).
The syntax will be simple:
1 SYS address

Now, insofar as this has significance due to the diversity of the various
CPUs, how is it possible to generalize such code? Actually, it is sufficient
to copy the binary code in a specific folder, different for each target,
and let ugBASIC load the exact version.
If the code is not relocatable, and it need to be loaded to a specific
memory location, you can use one of the options of the LOAD command,
i.e. the one that indicate in which position to load the code:
1 executable := LOAD (" e x e c u t a b l e _ i n c r e m e n t . bin " , 49152)

Obviously, VARPTR(executable) will return 49152. Note that, in this

way, it will still be necessary to pay attention to the space used by

224
 14.2 Passing parameters and return values

ugBASIC, as there are no particular checks and therefore it is possible

that the compiled ugBASIC collides with the space loaded.

14.2 Passing parameters and return values

14.2.1 Using registers

We saw how the SYS (EXEC) command will allow you to recall a pre-
compiled and relocatable machine code from outside. For all this to be
useful, it is necessary to give the possibility to communicate with the
machine code. This will be made possible by indicating, at the same
time as the call, the population of specific ”input” registers and the
recovery of values from specific ”output” registers.
The syntax we will use will be this:
1 SYS address WITH REG ( r1 ) = v1 , REG ( r2 ) = v2 , ... RETURN x1 = REG ( r1 )
, x2 = REG ( r2 ) , ...

Where r1, r2, ... are the various processor registers, v1, v2, ... are the
values passed in the various registers and x1, x2, ... are the variables
that will receive the execution result from the various registers.

Since the registers are different from CPU to CPU, it will be necessary
to introduce some tricks to make the code as portable as possible.
First, let’s write a small assembly program that increments one of the
registers by one. This is an example for Zilog Z80:
1 INC B
2 RET

We assemble it in the executable increment.bin file obtaining an ex-

ecutable file that we will load with the previous commands. At this
point, we pass the value to increment with the above syntax.

225
 14 Assembly

For example, this program monotonically increments the variable x at

each keystroke:
1 executable := LOAD (" e x e c u t a b l e _ i n c r e m e n t . bin ")
2 address = VARPTR ( executable )
3 x = 0
4 DO
5 SYS address WITH REG ( B ) = x RETURN x = REG ( B )
6 PRINT x
7 WAIT KEY
8 LOOP

The program, as written, works on any computer with a Z80 processor.

14.2.2 Using stack

There is also a different way of passing parameters: instead of using

registers, which are limited in number, you can use the stack. Which
is still a limited resource but capable of hosting a greater number of
parameters.

226
 14.2 Passing parameters and return values

The syntax for using the stack is simple:

1 SYS address WITH STACK ( ta1 ) = v1 , STACK ( ta2 ) = v2 , ... RETURN x1 =
STACK ( tb1 ) , x2 = STACK ( tb2 ) , ...
2 op1 = 42: op2 = 21
3 SYS address WITH STACK ( WORD ) = op1 , STACK ( WORD ) = op2 RETURN sum =
STACK ( WORD )
4 PRINT sum

One important thing: the elements are pushed onto the stack in reverse
order of how they appear in the list, so that the caller finds them in the
expected order.

227
14 Assembly

In this specific case, on the stack we will first find the value of op2 and
then the value of op1, but the called program will assign the value of
op1 to the DE register while the value of the op2 parameter to the HL
register.
Note that if you use the stack, porting between different processors
is easier since all processors have a stack: this is a classic case of
isomorphism.

14.3 Portable assembly code

Assembly code is tightly coupled to the processor architecture. A block

of assembly code written for a Zilog Z80 will not run on an MOS 6502.
Moreover, it is less readable than ugBASIC language, making it more
difficult to maintain.

As we wrote a small assembly program that increments a variable, and

that runs on Zilog Z80 based computers. Let’s imagine we want to do
the same thing with the Motorola 6809 processor.
First, let’s write and assemble a similar program, obviously using another
register:

228
 14.3 Portable assembly code

1 INCA
2 RTS

We already suggested moving the compiled executable directly to a

path that has the name of the target. So, for example, if we want
to recompile the example for the TRS-8O Color Computer, it will be
enough to call the program in the same way as the previous one but
put it in the coco subdirectory.
Now let’s go back to the source. As written it cannot work because it
uses the wrong registry. How can we differentiate our code to run on
other processors, without writing multiple versions of the same? Simple:
let’s use ugBASIC’s conditional compilation!

For example, this program increments variables for both the Z80 pro-
cessor and the 6809 processor.
1 DIM x AS BYTE
2 executable := LOAD (" e x e c u t a b l e _ i n c r e m e n t . bin ")
3 address = VARPTR ( executable )
4 GLOBAL x , address
5 x = 0
6 DO
7 SYS address WITH REG ( B ) = x RETURN x = REG ( B ) ON CPUZ80
8 SYS address WITH REG ( A ) = x RETURN x = REG ( A ) ON CPU6809
9 PRINT x
10 LOOP

We finish the integration by writing the assembly routine, and the re-
lated function, for the MOS 6502 processor.
1 INX
2 RTS

1 SYS address WITH REG ( X ) = x RETURN x = REG ( X ) ON CPU6502

Let’s remember to add the call and see how the count appears also on
the Commodore 128, which is indeed equipped with this processor.

229
 14 Assembly

14.4 Inlining assembly code

Inline assembly is definitely a convenience because it allows you to in-

sert assembly language directly into the ugBASIC source. Unlike what
happens with BASIC source, the assembly language is not interpreted
by the compiler but passed “as is” to the assembler. This means that
it is necessary to know well how both the syntax and the semantics of
these assemblers work, and to have a good understanding of how the
ugBASIC “internals” work.
In some sections of the code, especially those that require maximum
performance or very precise control over the hardware, writing directly
in assembly can bring significant speed improvements. Assembly allows
you to interact directly with the registers and instructions of the CPU,
offering granular control over the hardware.
When dealing with code that must run on different architectures, as-
sembly can be used to write portions of code that are highly optimized
for a specific platform.

Inline assembly should be used sparingly and only when absolutely nec-
essary. It is best used for small sections of performance-critical code,
for direct access to processor-specific registers or instructions and to
Interface with legacy code or specific hardware.
In this chapter we’ll see a really simplified approach to inline assembly,
and in the next ones we’ll see how to enable specific additional fea-
tures. The simplest way to define an assembly piece is to use the ASM
instruction:
1 ASM LDA # $42

This instruction causes the processor A register to be loaded with the

value 42 hexadecimal, at least on MOTOROLA 6809 and MOS 6502
processors, while it will generate a syntax error for the Z80 CPU. To
avoid the error message, a conditional compilation can be used.

230
 14.5 Importing procedures and functions

1 ON CPU6510 ASM LDA # $42

2 ON CPU6809 ASM LDA # $42
3 ON CPUZ80 ASM LD A , $42

Obviously it is also possible to write a small piece of code of several

lines: in this case the construct BEGIN ASM ... END ASM can be
used, always prefixed with the indication of the processor (or even the
target) for which it is valid:
1 DIM x AS BYTE
2 x = 41
3 ON CPUZ80 BEGIN ASM
4 LD A , ( _x )
5 LD B , A
6 INC B
7 LD A , B
8 LD ( _x ) , A
9 END ASM
10 ON CPU6502 BEGIN ASM
11 CLC
12 LDA _x
13 ADC #1
14 STA _x
15 END ASM
16 ON CPU6809 BEGIN ASM
17 LDA _x
18 INCA
19 STA _x
20 END ASM
21 PRINT x

14.5 Importing procedures and functions

We have seen how to call functions in machine language and how to

insert some pieces of assembly into the sources. Now let’s move on to
the last aspect of integration: how it declares functions and procedures
that can be called as if they were an integral part of the language.
First, we introduce a mechanism for defining the pattern for calling a
procedure.

231
 14 Assembly

The simplest syntax is this:

1 DECLARE PROC name AT address [ ON target ]

(you can also use PROCEDURE instead of PROC). For example, suppose
you have an assembly routine at address &HC000 and it only works
under the Commodore 64. You can declare it like this:
1 DECLARE PROC test AT $C000 ON C64

At this point it will be sufficient to invoke it with one of the following

syntaxes:
1 CALL test
2 PROC test
3 test []

as if it were any ugBASIC procedure. If desired, parameters can be

added. For each it is obviously necessary to indicate how the value will
be passed to the function written in machine language. The syntax is
like this:
1 DECLARE PROC name AT address ( p1 [ AS t1 ] ON r1 , ... ) [ ON
target ]

Where p1, p2, ... are the parameters, t1, t2, ... are the (ugBASIC)
data types, and finally r1, r2, ... are the descriptions of where the
values will go.
For example, if we want to create a function that sends data to the
serial port, and the data (as bytes) needs to be pushed onto the stack,
we just need to write the following declaration:
1 DECLARE PROC serial AT $c000 ( value AS BYTE ON STACK ( BYTE ) )

We have seen how to import a procedure. Importing a function is just

as easy. The mechanism for defining the pattern for calling an imported
function is this:
1 DECLARE FUNCTION name AT address RETURN rt AS tt [ ON targets ]

232
 14.5 Importing procedures and functions

For example, suppose you have an assembly routine at address $C000

and it only works under the Commodore 128, and returns a byte on A
register. You can declare it like this:
1 DECLARE FUNCTION test AT $C000 RETURN REG ( A ) AS BYTE ON C128

At this point it will be sufficient to invoke it with one of the following

syntax:
1 x = test []

Alternatively, you can call it as a procedure and retrieve the parameter

later, with the PARAM command:
1 CALL test
2 PROC test
3 test []
4 ...
5 x = PARAM ( test )

If desired, you can add parameters. For each it is, of course, necessary to
indicate how the value will be passed to the function written in machine
language. The syntax is like this:
1 DECLARE FUNCTION name AT address ( p1 [ AS t1 ] ON r1 , ... )
RETURN rt AS tt [ ON targets ]

Where p1, p2, ... are the parameters, t1, t2, ... are the (ugBASIC)
data types, r1, r2, ... are the descriptions of where the values will go
and rt is the description of where the result will be stored, as the tt
ugBASIC type. For example, if we want to create a function that sends
data to the serial port, and the data (as a byte) is placed on the stack,
and then the function returns the status of the sending, it is sufficient
to write the following declaration in the A register of the CPU 6502,
we will have:
1 DECLARE PROC serial AT $c000 ( value AS BYTE ON STACK ( BYTE ) )
RETURN REG ( A ) AS BYTE ON CPU6502

233
 14 Assembly

14.6 System functions

The ugBASIC compiler allows you to declare functions and procedures

that are ”system” one. It means that the machine code resides in a
ROM, preloaded at run time and therefore already made available to
any program that knows how to call it.
However, since ugBASIC makes available all memory space allowed by
the hardware, it is possible that the ROMs have been disabled or oth-
erwise made unreachable. Indicating that you want to call a procedure
or a system function, ugBASIC will take care of re-enabling the ROM
before executing the request, deactivating it on exit.
To declare a procedure or function to be system, simply use the SYS-
TEM keyword. For example, this system procedure on the Commodore
64 scans the keyboard, verifying that a key has been pressed:
1 DECLARE SYSTEM PROC scnkey AT $FF9F ON C64

The ugBASIC compiler already has several declarations of functions or

system procedures, declined for the various targets. They are located in
the imports folder on the repository. You can request their automatic
inclusion by using the IMPORT DECLARES command.

234
15 Keywords
In this chapter, we will explore in detail the keywords that make up the
vocabulary of this language. For each keyword, we will give:

• SYNTAX

• PURPOSE
• AVAILABLE ON - the list of targets where the keyword is avail-
able (if missing, the keyword sould be available on all targets);
• EXAMPLES

Note that, when a keyword is not implemented on a target, using it has

no effect. We also use this convention:

• UPPERCASE - keyword(s);

• parameter - mandatory;
• [parameter] - optional.

235
 15 Keywords

15.1 $$

SYNTAX

= $$(expression)

PURPOSE
Alias for HEX

EXAMPLES
1 x = $$ ( 42 )
2 PRINT $$ ( y )

236
 15.2 %%

15.2 %%

SYNTAX
= %%(expression)

PURPOSE
Alias for BIN
EXAMPLES
1 x = %%( 42 )
2 PRINT %%( y )

237
 15 Keywords

15.3 ABS

SYNTAX
= ABS(expression)

PURPOSE
The ABS command is a mathematical function that returns the abso-
lute value of a number. In essence, it removes the negative sign from
a number, always returning a positive or zero value. The parameter
expression is the value whose absolute value you want to calculate.
This can be a constant numeric value, a variable, or a mathematical
expression.
The ABS command is very useful in several situations. When calculating
the distance between two points, the absolute value ensures that the
distance is always positive, regardless of the order in which you consider
the points. You can use ABS inside conditions to test whether a value is
greater than or less than a certain threshold, ignoring the sign. In many
applications, you need to work with absolute values to avoid errors or
unexpected results.

The ABS command can be applied only to integers.

Abbreviated as Ab
EXAMPLES
1 ’ Calculate the distance between two abscissa
2 distance = ABS ( x1 - x2 )

238
 15.4 ADD

15.4 ADD

SYNTAX
ADD var, expr [, min TO max]

PURPOSE
The ADD statement is used to increment the value of a numeric variable
by a specified amount. In other words, it is like adding one number to
another.

The basic syntax take the var to which you want to add a value and
the expr as the expression you want to add to the variable. The full
syntax takes also two additional parameters: min and max, that are
the minimum and maximum value that the variable can take after the
increment. In other words, the var is incremented, but its value is
”squeezed” between min and max. If the result of the addition had
been greater than max, the level would still have been set to max.
The purpose of this second syntax is to prevent a variable from taking
invalid value for your program. It can also help to simulating real-world
systems: for example, in a game you can limit a character’s life between
0 and 100. This instruction can also help to create special effects: you
can create bouncing or wrapping effects, by making a variable ”bounce”
between two values. In videogames, the typical use is to limit the max-
imum score in a game, or to preventing a difficulty level from exceeding
a certain value.

Abbreviated as Ad
EXAMPLES
1 ADD y ,10
2 ADD x ,42 ,1 TO 100

239
 15 Keywords

15.5 ADDRESS (data type)

SYNTAX
... AS ADDRESS

PURPOSE
Data type ADDRESS represents a 16-bit address, that is used by proces-
sors to access computer’s memory. The memory address is represented
by a binary number of 16 digits (bits). With 16 bits, we can represent
21̂6 = 65,536 different addresses.
Abbreviated as A#
EXAMPLES
1 DIM limit AS ADDRESS = & H8000

240
 15.6 AFTER...CALL

15.6 AFTER...CALL

SYNTAX
AFTER value[,timer] TICKS CALL identifier

PURPOSE
The AFTER...CALL command implement a countdown timer for your
program. It is a very useful tool for making a piece of code run after
a specific interval, essentially turning your program into a countdown.
You must specifying the length of time to wait, measured in TICKS.
When the timer reaches the specified timer, the program stops executing
the current code and jumps to the PROCEDURE indicated by the label.
After executing the routine, the program returns to where it left off and
resumes execution. After the call, the timer is disabled. You must use,
again, the AFTER...CALL to enable again the mechanism.
There are 8 delay timers from 0 to 7 which can be specified with timer
parameter. If omitted, timer will be considered as 0. In the case of
parallel timers, 0 will be the highest and 7 the lowest priority.

With EVERY OFF and EVERY ON you can disable or enable the timed
calls. It is important to know or realise that low-priority-procedures
which occurs simultanously to higher-priority-procedures are not lost.
Their task remains or handled again after finishing the higher-prio in-
terrupt.

Finally, note that the accuracy of the timer can vary depending on
hardware and operating system, and it can be used to create animations,
simulate real-time events, or simply to execute tasks after a specific
time.
Abbreviated as AfCa

241
 15 Keywords

EXAMPLES
1 AFTER 50 TICKS CALL c h a n g e B o r d e r C o l o r
2 AFTER 50 ,2 TICKS CALL c h a n g e B o r d e r C o l o r

242
 15.7 AFTER...GOSUB

15.7 AFTER...GOSUB

SYNTAX
AFTER value[,timer] TICKS GOSUB label

PURPOSE
Define the call of a subroutine after a specific time, without interfering
with the main program. You must specifying the length of time to
wait, measured in TICKS. The ugBASIC branches to the subroutine
after value/TICKS PER SECONDS seconds.
There are 8 delay timers from 0 to 7 which can be specified with timer.
If omitted timer defaults to 0. In the case of parallel task has 0 the
highest and 8 the lowest priority.

With EVERY OFF and EVERY ON you can disable or enable the timed
calls. It is important to know or realise that low-priority-subroutines
which occurs simultanously to higher-priority-subroutines are not lost.
Their task remains or handled again after finishing the higher-prio in-
terrupt.

Abbreviated as AfGs
EXAMPLES
1 AFTER 50 TICKS GOSUB 100
2 AFTER 50 ,2 TICKS GOSUB label

243
15 Keywords

15.8 ALLOW

SYNTAX
ALLOW

PURPOSE
The ALLOW instruction is the opposite of the FORBID function. While
FORBID completely blocks multitasking, ALLOW re-enables it, allowing
ugBASIC to schedule again the execution of other tasks, passing the
execution from one task to another according to its scheduling policy.
If a PROCEDURE has previously called FORBID to assure exclusive access
to the CPU, ALLOW returns control to the other procedures, allowing
other procedures to continue execution.
Note that this type of control is ”static”: in other words, compilation
will stop if the procedure that called FORBID subsequently wants to call
a function that would require multitasking to be active. The call to
ALLOW will restore multitasking, and allow routines of this type to be
called.
Once a procedure has finished executing a section of code that required
exclusive access to the processor, it should call ALLOW to allow other
tasks to be executed.
If a task needs to wait for an event (for example, a signal), it can call
ALLOW before entering a waiting state, allowing other tasks to execute
their code while the waiting task is suspended.

Using FORBID and ALLOW in a balanced way is essential to achieve both

good performance and correct synchronization between parallel proce-
dures. In many cases, more sophisticated synchronization mechanisms,
such as shared variables, could be used without completely disabling
multitasking.

244
 15.8 ALLOW

See also FORBID

Abbreviated as Alw
EXAMPLES
1 PARALLEL PROCEDURE test
2 FORBID
3 ’ busy waiting , multitasking is suspended !
4 FOR i =0 TO 1000: WAIT 1 MS : NEXT i
5 ALLOW
6 END PROC

245
15 Keywords

15.9 ALT LEFT (constant)

SYNTAX
= LEFT ALT

PURPOSE
This constant represent the left ”ALT” key, when used as bitmask for
KEY SHIFT instruction.

Alias for LEFT ALT (constant)

Abbreviated as AlLf

246
 15.10 ALT RIGHT (constant)

15.10 ALT RIGHT (constant)

SYNTAX
= RIGHT ALT

PURPOSE
This constant represent the left ”ALT” key, when used as bitmask for
KEY SHIFT instruction.

Alias for RIGHT ALT (constant)

Abbreviated as AlRg

247
15 Keywords

15.11 AND

SYNTAX
= x AND y

PURPOSE
Performs a logical conjunction on two expressions, as a bitwise conjunc-
tion. For comparisons managed as a boolean result (TRUE or FALSE),
result is TRUE if, and only if, both expresions evaluate to TRUE. The
following table shows how result is determined:
TRUE AND TRUE = TRUE
TRUE AND FALSE = FALSE
FALSE AND TRUE = FALSE
FALSE AND FALSE = FALSE

Generally speaking, the AND operator performs a bitwise comparison of

the bits of two numeric expressions and sets the corresponding bit in
result according to the previous table.
Note that ugBASIC uses the convention, very common in BASICs of the
1970s and 1980s, of considering Boolean logic as implemented through
the so-called ”two’s complement”.
In other words, the value FALSE is associated with a number composed
of all 0s, in terms of bits. The value TRUE is, instead, associated with a
number composed of all 1s, again in terms of bits. According to the 2’s
complement representation, a number composed of all ones is always
equivalent to the number -1, regardless of how many bits the number is
composed of, while a number composed of all zeros is always equivalent
to zero.
According to this convention, there is a coincidence between bitwise

248
 15.11 AND

and logical operations: in fact, a bitwise AND, applied to all the bits
of the number, will be equivalent to the logical operation. Note tha
the AND operator always evaluates both expressions, which can include
executing routine calls.

Because the logical and bitwise operators have lower precedence than
other arithmetic and relational operators, all bitwise operations must be
enclosed in parentheses to ensure accurate results.
If the operands consist of a SIGNED BYTE expression and a numeric
expression, converts the SIGNED BYTE expression to a numeric value
(-1 for TRUE and 0 for FALSE) and performs a bitwise operation. So,
the data type of the result is a numeric type appropriate for the data
types of both expressions.
Abbreviated as An

EXAMPLES
1 IF x AND 1 THEN
2 PRINT " x is odd "
3 ELSE
4 PRINT " x is even "
5 ENDIF

249
 15 Keywords

15.12 ARRAY

SYNTAX
ARRAY var = ...
ARRAY var := ...

PURPOSE
The ARRAY keyword allows you to copy a block of memory from a static
definition to an array at run time. In simple terms, it copies an array
of bytes from the right expression to a var. It is especially useful when
you want to initialize an array with a specific value or assign an entire
array.
This method is generally faster than copying element by element, es-
pecially for large arrays. It provides a concise way to initialize an entire
array with a constant value.
If you want to initialize an array to a single byte, memset is more
efficient. For small arrays or when initializing elements with different
values, direct assignment can be more readable.

Abbreviated as Ar
EXAMPLES
1 DIM var (4) AS BYTE
2 ARRAY var = #{42424242}

250
 15.13 ARROW LEFT (constant)

15.13 ARROW LEFT (constant)

SYNTAX
= ARROW LEFT

PURPOSE
This constant represent the left arrow key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Alias for LEFT ARROW (constant)

Abbreviated as AwLf
EXAMPLES
1 IF KET STATE ( ARROW LEFT ) THEN
2 PRINT " LEFT ARROW has been pressed !"
3 ENDIF

251
 15 Keywords

15.14 ARROW UP (constant)

SYNTAX
= ARROW UP

PURPOSE
This constant represent the up arrow key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Alias for UP ARROW (constant)

Abbreviated as AwUP
EXAMPLES
1 IF KET STATE ( ARROW UP ) THEN
2 PRINT " UP ARROW has been pressed !"
3 ENDIF

252
 15.15 ASC

15.15 ASC

SYNTAX

= ASC( string )

PURPOSE
The ASC command performs a very specific function: it converts the
first character of a string into its corresponding ASCII code. ASCII
stands for American Standard Code for Information Interchange and it
is a standard encoding that associates each alphanumeric character and
many symbols with an integer between 0 and 127. This number repre-
sents the internal representation of the character within the computer.
The ASC command allows you to manipulate the individual characters
of a string numerically. For example, you can check whether a character
is an uppercase letter (its ASCII code will be between 65 and 90), or
whether it is a number (its ASCII code will be between 48 and 57).
Comparing the ASCII codes of two characters is an efficient way to
establish the alphabetical order between them and, in some applications,
you need to convert characters to numbers or vice versa. ASC is a
fundamental tool for this type of operation.
In 8-bit computers, memory is organized in bytes, which are sequences
of 8 bits. Each byte can represent a number from 0 to 255. Since ASCII
encoding uses only 7 bits, a byte can represent 128 different characters.
On 8-bit computers, the supported character set is limited to 128 ASCII
characters. This means that accented characters or characters from
other languages cannot be directly represented. The exact meaning of
an ASCII code can vary slightly depending on the encoding used. Note
that the CHR$ command is the inverse of ASC, it converts an ASCII
code to a character.

253
 15 Keywords

See also CHR

Abbreviated as Ax
EXAMPLES
1 x = ASC ( " UGBASIC " )

254
 15.16 ASCII CODE

15.16 ASCII CODE

SYNTAX
= ASCII CODE

PURPOSE
The ASCII CODE command capture a keystroke ”on the Fly”, and re-
turn the equivalent ASCII code instead of internal SCANCODE. This com-
mand is a fundamental tool for making programs more interactive. It
allows you to read a character typed by the user without having to press
the enter key.
Unlike other input commands, ASCII CODE does not require the user
to press Enter to send the character, while the typed character is not
displayed on the screen. It return directly the ASCII code of the typed
character, or a special value (0) if no key was pressed. It is equivalent
to write ASC( INKEY$() ), but faster, since no string is created. Note
that the reading speed could vary significantly depending on the target.
This command allows you to create simple games in which the user
must press specific keys to control a character or object. It can be
used to create more responsive user interfaces, in which the user can
interact with the program in real time or that respond to certain key
combinations, automating certain operations.
Due to the limitations of 7-bit ASCII encoding, ASCII CODE could only
read characters in the standard ASCII set. Use SCANCODE if you need
to be able to detect any key.
Alias for ASCIICODE
See also SCANCODE
Abbreviated as AsciiCo

255
 15 Keywords

EXAMPLES
1 IF ASCII CODE = 42 THEN
2 PRINT " ASTERISK has been pressed !"
3 ENDIF

256
 15.17 ASCIICODE

15.17 ASCIICODE

SYNTAX
= ASCIICODE

PURPOSE
Alias for ASCII CODE
See also SCANCODE

EXAMPLES
1 IF ASCIICODE = 42 THEN
2 PRINT " ASTERISK has been pressed !"
3 ENDIF

257
15 Keywords

15.18 ASM

SYNTAX
ASM line
BEGIN ASM
...
END ASM

PURPOSE

The ASM command is a bridge between ugBASIC and the assembly lan-
guage. It allows you to directly insert instructions in machine language
or assembly language into the source code.
In some sections of the code, especially those that require maximum
performance or very precise control over the hardware, writing directly
in assembly can bring significant speed improvements. Assembly allows
you to interact directly with the registers and instructions of the CPU,
offering granular control over the hardware.
When dealing with code that must run on different architectures, as-
sembly can be used to write portions of code that are highly optimized
for a specific platform. In some cases, you may need to interface with
code written in assembly or with pre-existing libraries.
The first syntax allow to introduce a single machine code for each line,
while the second one allows to introduce multiple lines, at once.

Note that assembly code is tightly coupled to the processor architecture.

A block of assembly code written for a Zilog Z80 will not run on an MOS
6502. Moreover, it is less readable than ugBASIC language, making it
more difficult to maintain. Finally, a single error in assembly can cause
the program to crash, and indiscriminate use of assembly can interact
with compiler optimizations.

258
 15.18 ASM

Inline assembly should be used sparingly and only when absolutely nec-
essary. It is best used for small sections of performance-critical code,
for direct access to processor-specific registers or instructions and to
Interface with legacy code or specific hardware.

Abbreviated as Asm
EXAMPLES
1 BEGIN ASM
2 LDA #02
3 STA $D020
4 END ASM ON CPU6502

259
 15 Keywords

15.19 ASTERISK (constant)

SYNTAX
= ASTERISK

PURPOSE
This constant represent the asterisk key, when used as a value to com-
pare with SCANCODE,KEY STATE and KEY PRESSED. If the key does not
exist in the corresponding target, the value will be zero.

Abbreviated as Ak
EXAMPLES
1 IF KET STATE ( ASTERISK ) THEN
2 PRINT " ASTERISK has been pressed !"
3 ENDIF

260
 15.20 AT (constant)

15.20 AT (constant)

SYNTAX
= AT

PURPOSE
This constant represent the ”at” (@) key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as At
EXAMPLES
1 IF KET STATE ( AT ) THEN
2 PRINT " ASTERISK has been pressed !"
3 ENDIF

261
 15 Keywords

15.21 AT (function)

SYNTAX
= AT$( x , y )
= AT( x , y )

PURPOSE
The AT function is used to create a string to position the cursor to an
exact position on the screen, when it will be printed on the screen. It’s
like telling a painter where to start painting on a canvas, not moving
immediately but storing the command in a string.
The AT function is followed by two expressions, separated by a comma:
x indicates the column in which move the cursor, while y will be the
line in which to start writing.

The string that is returned takes the standard format. So whenever this
string is printed, the text cursor will be moved to the text coordinates
held by x and y.
See also LOCATE (function)

Abbreviated as At
EXAMPLES
1 PRINT AT$ (10 ,10) ; " at 10 , 10"

262
 15.22 AT (instruction)

15.22 AT (instruction)

SYNTAX
AT var1, var2

PURPOSE
The AT command is used to swap the values of two string variables. In
practice, the reference of the first variable are assigned to the second
and vice versa, in a single operation, and without memory movement.
Infact, the AT command actually performs a similar operation at the
machine level, but more efficiently and hidden from the programmer.
The AT command makes code more concise and readable by avoiding
the use of a temporary variable for swapping. Using this command is a
fundamental operation in many sorting algorithms with array of strings,
such as bubble sort. In general, swapping strings is a common operation
in many programs, and AT provides a simple and efficient way to do it.
This command can only be used with variables of the type string.
See also SWAP

Abbreviated as At
EXAMPLES
1 a$ = " primo " : b$ = " secondo "
2 AT a$ , b$
3 PRINT a$ , b$

263
15 Keywords

15.23 ATLAS (data type)

SYNTAX
... AS ATLAS

PURPOSE
The ATLAS data type maintains a reference to the collection of images
that can be used to draw them on the screen.

Alias for IMAGES

Abbreviated as Atl#

264
 15.24 ATLAS LOAD

15.24 ATLAS LOAD

SYNTAX
PURPOSE

Alias for LOAD ATLAS, LOAD IMAGES, IMAGES LOAD

Abbreviated as Atl#Ld

265
 15 Keywords

15.25 BANK

SYNTAX
BANK id

PURPOSE
The BANK command allows you to change the currently selected bank.
All operations that are performed on the banks, and that do not explic-
itly indicate the bank to operate on, work with the implicit bank, which
is set by this command. The minimum bank number is zero (0) while
the maximum is equal to BANK COUNT - 1.
See also BANK COUNT (constant)
Abbreviated as Bk

EXAMPLES
1 BANK #1

266
 15.26 BANK (function)

15.26 BANK (function)

SYNTAX
= BANK()

PURPOSE
The BANK function allows you to know the currently selected bank. All
operations that are performed on the banks, and that do not explicitly
indicate the bank to operate on, work with this implicit bank.

See also BANK

Abbreviated as Bk
EXAMPLES
1 x = BANK ()

267
 15 Keywords

15.27 BANK ADDRESS

SYNTAX
= BANK ADDRESS(id)

PURPOSE
The BANK ADDRESS function allows you to know the memory address
where the swap window with the expanded memory appears, for the
given bank. In the case of expansion memories with DMA access, this
area does not exist and therefore the function returns zero. Exactly the
same value returned in case there are no memory expansions.
See also BANK, BANK COUNT (constant)
Abbreviated as BkA#

EXAMPLES
1 x = BANK ADDRESS (1)

268
 15.28 BANK COUNT (constant)

15.28 BANK COUNT (constant)

SYNTAX
= BANK COUNT

PURPOSE
This function returns the number of expanded memory banks available
to the program. Depending on the target, this number can range from
zero to the actual number of banks.

See also BANK, BANK ADDRESS

Abbreviated as BkC%
EXAMPLES
1 IF BANK COUNT > 0 THEN
2 PRINT " there are banks !"
3 ENDIF

269
 15 Keywords

15.29 BANK READ

SYNTAX
BANK READ bank FROM address1 TO address2 SIZE size

PURPOSE
This instruction can be used to read a number of bytes from an out-of-
memory bank in main memory. You must therefore indicate one of the
available banks, the memory address from which you want to copy (the
$0000 implies the beginning of the bank), the size in bytes and finally
the destination address, which will be the RAM memory.
Note that, if the destination of read is an array, the array must be
declared with the flag FOR BANK READ.

Abbreviated as BkR#
EXAMPLES
1 BANK READ 1 FROM $0100 TO $2000 SIZE 128

270
 15.30 BANK WRITE

15.30 BANK WRITE

SYNTAX
BANK WRITE bank FROM address1 TO address2 SIZE size

PURPOSE
This instruction can be used to write a number of bytes to an out-of-
memory bank from main memory. You must therefore indicate one of
the available banks, the memory address from which you want to copy,
the size in bytes and finally the destination address (the $0000 implies
the beginning of the bank), which will be the bank memory.
Abbreviated as BkW#
EXAMPLES
1 BANK WRITE 1 FROM $0100 TO $2000 SIZE 128

271
 15 Keywords

15.31 BANK...AT

SYNTAX
BANK [id] AT #address [AS type] [WITH filename]

PURPOSE
Define a bank of memory named id, starting from address and of type
type. Optionally, fill the bank of memory with static data coming from
a specific filename.

D
Available type: CODE for executable code (binary), VARIABLES for pro-

E
gram’s variables, TEMPORARY for temporary variables and DATA for un-
specified data.
AT
If id is missing, the bank will have an unique name. If type is missing,
the default type is DATA. If filename is missing, the default is a simply
memory reservation.
EC

See also VAR

Abbreviated as BkAt
PR

EXAMPLES
1 BANK VARIABLES AT $c000
DE

272
 15.32 BAR

15.32 BAR

SYNTAX
BAR [x1], [y1], [x2], [y2], [c]
BAR [x1], [y1] TO [x2], [y2]
BAR TO [x2], [y2][, c ]

PURPOSE

The BAR instruction will draw a filled rectangle on the screen, specifying
the coordinates of its opposite corners. The x1 and y1 are the left top
coordinates, while the x2 and y2 are the right bottom coordinates.
The fill color could be the one predefined, or specified by additional
parameter. The start or the final coordinates can be omitted: in this
case, ugBASIC will draw, respectively, starting from the last drawn
position and arriving at the last drawn position.
Drawing (and filling) rectangles is a common operation in graphics. A
dedicated command would make the code more concise and readable.
Filled rectangles can be used to create buttons, text boxes, and other
interface elements. The BAR command could be used as a basis for
creating more complex shapes.
Abbreviated as Br
EXAMPLES
1 BAR 10 ,10 ,100 ,100 , WHITE
2 BAR TO 100 ,100
3 BAR ,10 TO ,100

273
15 Keywords

15.33 BEGIN GAMELOOP

SYNTAX
BEGIN GAMELOOP

PURPOSE
The command BEGIN GAMELOOP define the starting point of the game
loop. A game loop is a fundamental concept in video game program-
ming, especially in simple video games like those for 8-bit computers.
Think of the game loop as the heartbeat of a video game: it is a con-
tinuous cycle of actions that are constantly repeated, giving life to the
gaming experience.
In simple terms, the game loop is an infinite loop in the game code that
takes care of: updating the game state, checking user input (button
presses, joystick movement), updating the position of objects on the
screen, calculating collisions, managing enemy AI, and so on.
The game loop is the place where drawing everything that needs to be
displayed on the screen, based on the current state of the game. In some
platforms, it will implictly ”sync” the activity with the vertical blank,
so the action inside the loop should be executed in a single ”frame” of
game.
On an 8-bit computer, with limited resources, the game loop was often
implemented in a very simple way, as an infinite loop. The BEGIN
GAMELOOP...END GAMELOOP instructions create an infinite loop, so that
the program would continue to execute the same instructions over and
over again. Inside the loop, instructions were executed to update the
game state, such as checking if a button had been pressed or if an enemy
had moved. After updating the state, a routine was called to draw
everything on the screen. The program would return to the beginning
of the loop, ready for the next iteration.

274
 15.33 BEGIN GAMELOOP

The game loop makes the game interactive, allowing the player to hit
what is happening on the screen, continuously updating the state and
redrawing the screen creates the illusion of movement and animation.
A well-designed game loop ensures a smooth and responsive gameplay
experience.
Abbreviated as BeGl
EXAMPLES
1 BEGIN GAMELOOP

275
 15 Keywords

15.34 BEGIN STORAGE

SYNTAX
BEGIN STORAGE [name] [AS filename]
STORAGE [name] [AS filename]

PURPOSE
The BEGIN STORAGE allows to begin describing the content of a stor-
age media. The syntax of this command allows to define up to two
parameter. The first parameter, name, refers to the internal name of
the storage. The filename, optional, will define the file name that will
contain the ”image” of the storage. If omitted, the program filename
will be used, and an additional incremented number will be appended,
one for each storage media.

Alias for STORAGE

See also ENDSTORAGE
Abbreviated as BeStr
AVAILABLE ON

atari c128 c64 c64reu coco coco3 cpc msx1 vic20

EXAMPLES
1 BEGIN STORAGE " dischetto "
2 ...
3 ENDSTORAGE

276
 15.35 BELL

15.35 BELL

SYNTAX
BELL
BELL note
BELL note, duration
BELL note, duration ON channels

PURPOSE

The BELL command makes the computer emit a sound, usually a short
beep, through the internal speaker or audio chipset. This sound serves
as an acoustic signal to the user, indicating that an action has been
completed, reporting an error, or simply to attract attention.
It can be used alone, or specifying characteristics of the sound to
be produced. When you use BELL with parameters, ugBASIC gener-
ates a sine wave with the frequency specified by the value, and of
duration length. The higher the value, the higher the pitch. The
greater duration, the greater time the sound will last.
The ability to specify the frequency opens up many creative possibilities:
by combining several BELL commands with different frequencies, you
can create short melodies; you could simulate the sounds of explosions,
pops, or other effects, depending on the frequency and duration of the
sound; you can create specific beeps to indicate different conditions or
events in your program.

The supported frequency range may vary depending on the hardware

of target computer. Typically, the duration of the sound produced by
BELL is short and can be controlled by another, additional, parameter.
Moreover, you can select a specific channel for audio output.
Executing the command may or may not interrupt program execution,

277
 15 Keywords

depending on the setting of DEFINE AUDIO SYNC. Not all targets sup-
port all settings (synchronous and asynchronous).
Abbreviated as Bel

AVAILABLE ON
atari atarixl c128 c64 coco coleco cpc d32 d64 mo5 msx1 pc128op
plus4 to8 vic20
EXAMPLES
1 BELL 42
2 BELL #42 ON #%001

278
 15.36 BETA (constant)

15.36 BETA (constant)

SYNTAX
= BETA

PURPOSE
This constant is set to non-zero if the compiler used to generate the
executable is in beta version. The beta version is not the final version
of the compiler, and may contain bugs or run unstable. This constant
helps to isolate the part of codes that depends on aspects available on
beta version only.
Abbreviated as Bet
EXAMPLES
1 IF NOT BETA THEN
2 PRINT " We are in a stable compiler ."
3 ENDIF

279
15 Keywords

15.37 BIG ENDIAN (constant)

SYNTAX
= BIG ENDIAN

PURPOSE
The BIG ENDIAN is a constant that values non zero if the rappresenta-
tion of data on the local CPU is in big endian. Endianness is a concept
that concerns the order in which the bytes of a multi-byte number are
stored in memory.
Imagine having an integer that spans more than one byte. Endianness
determines whether the most significant byte (the one that represents
the highest digit) is stored first (at the lowest memory address) or last.
In this case, the most significant byte is stored first. It is like reading a
book from left to right, starting with the most important word.

Endianness is a fundamental aspect of computer architecture, as it af-

fects how data is interpreted and manipulated. Different architectures
use different endianness conventions. For example: Motorola 6809 is
BIG ENDIAN, MOS 6502 is LITTLE ENDIAN.

In 8-bit computers, endianness was a crucial consideration, especially

when it came to managing integers across multiple bytes. Since these
computers had limited memory, it was essential to maximize storage
space.
With limited memory available, it was essential to use each byte effi-
ciently, and endianess directly affected arithmetic operations on multi-
byte numbers, such as addition and subtraction. Moreover, when ex-
changing data between systems with different endianness, appropriate
conversions is needed.
If you are writing code that directly manipulates memory, it is essential

280
 15.37 BIG ENDIAN (constant)

to know the endianness of the system to avoid data interpretation errors.

If you are developing software that needs to run on different platforms,
you need to account for endianness differences and implement data
conversion mechanisms, for data that are not manager by ugBASIC
itself.
See also LITTLE ENDIAN (constant)
Abbreviated as BigEnd
EXAMPLES
1 IF BIG ENDIAN THEN
2 PRINT " This CPU is big endian "
3 ENDIF

281
 15 Keywords

15.38 BIN

SYNTAX
= BIN( value [, digits] )

PURPOSE
The BIN command allows you to convert a decimal number into a
binary representation. In other words, it takes a number that we are
used to writing in base 10 (with the digits 0 through 9) and turns it
into a sequence of 0s and 1s, which is the base that computers use to
represent data internally. It decode from the most significant to the
least significant.
It is also possible to indicate the number of digits to be represented. If
this parameter is omitted, the minimum number of digits for that data
format (8, 16 or 32 digits) will be used.
This command is essential for those who want to delve deeper into
how computers work at a lower level. Infact, this command allows
you to operate directly on individual bits of a number, which is useful
in some applications such as graphics or communications. Moreover,
many encryption algorithms rely on bit-level operations.
Abbreviated as Bi
EXAMPLES
1 x = BIN (42)
2 z = BIN (42 , 5)

282
 15.39 BIT (data type)

15.39 BIT (data type)

SYNTAX
... AS BIT

PURPOSE
The BIT data type is the smallest unit of information in a computer,
it takes up very little memory, since ut is ”packed” on the minimum
number of bytes. This data type can be used to create compact and
efficient data structures, such as ”bitsets”, just using them in an array.
Abbreviated as Bt

283
 15 Keywords

15.40 BIT (function)

SYNTAX
= BIT( value, position )

PURPOSE
Alias for HAS BIT, BIT OF
Abbreviated as Bt

EXAMPLES
1 IF BIT ( 2 , x )
2 PRINT " bit 2 is 1!"
3 ENDIF

284
 15.41 BIT...OF

15.41 BIT...OF

SYNTAX
= BIT position OF value

PURPOSE
Alias for HAS BIT, BIT (function)
Abbreviated as BtOF

EXAMPLES
1 IF BIT 2 OF x THEN : PRINT " bit 2 is 1!": ENDIF

285
 15 Keywords

15.42 BITMAP (constant)

SYNTAX
... = BITMAP
= BITMAP

PURPOSE
This is the bitmask used to select the BITMAP mode.

D
The BITMAP constant represents the position (in terms of bits) that
tracks whether the graphics chipset is capable of rendering graphics in

E
”bitmap” mode, i.e. whether it is possible to address individual pixels
on the screen.
AT
This constant can be used to query the SCREEN constant, in an attempt
to understand whether the functionality is available or not.
EC

See also TILEMAP (constant), SCREEN (constant)

Abbreviated as Bm
PR

EXAMPLES
1 IF SCREEN IS BITMAP THEN : PRINT " bitmap is native !": ENDIF
2 IF BIT BITMAP OF SCREEN THEN : PRINT " bitmap is available !":
ENDIF
DE

286
 15.43 BITMAP AT

15.43 BITMAP AT

SYNTAX
BITMAP AT address

PURPOSE
The BITMAP AT instruction allows you to change the starting address
of the bitmap, in the graphics modes of the video chipset. Since not all
chipsets can address any address, it is possible that the input value is
normalized. This normalized address will then be used by ugBASIC for
subsequent graphics operations.
Abbreviated as BmAt
AVAILABLE ON

c128 c64 c64reu coco coco3 d32 d64 mo5 pc128op plus4 to8 vic20

EXAMPLES
1 BITMAP AT $8000

287
 15 Keywords

15.44 BITMAP CLEAR

SYNTAX
BITMAP CLEAR [ WITH value ]

PURPOSE
Fill the bitmap with a certain pattern (by default is ZERO, used to
indicate the blank screen). The filled part is exclusively that linked to
the bitmap, so the color information is kept unchanged.

D
Note that bitmap must be enabled at least once with instruction BITMAP

E
ENABLE. AT
See also BITMAP ENABLE, CLS

Abbreviated as BmClr
EC
AVAILABLE ON
atari c128 c128z c64 coleco cpc msx1 plus4 sc3000 sg1000
vic20 zx
PR

EXAMPLES
1 BITMAP CLEAR
2 BITMAP CLEAR WITH # $42
DE

288
 15.45 BITMAP DISABLE

15.45 BITMAP DISABLE

SYNTAX
BITMAP DISABLE

PURPOSE
The BITMAP DISABLE command disables bitmap graphics on the target
machine.

See also BITMAP ENABLE

Abbreviated as BmDx
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3 d32 d64 mo5 pc128op
plus4 to8
EXAMPLES
1 BITMAP DISABLE

289
15 Keywords

15.46 BITMAP ENABLE

SYNTAX
BITMAP ENABLE
BITMAP ENABLE (colors)
BITMAP ENABLE (width, height)
BITMAP ENABLE (width, height, colors)

PURPOSE

The ”BITMAP ENABLE’ command is a fundamental tool, since it al-

lows to configure the graphics mode of the screen, that is, to define
how data was displayed on the screen, determining aspects such as the
number of horizontal and vertical pixels that make up the image on the
screen, and the color palette available for drawing images.

In 8-bit computers, memory was limited and processing power was much
lower than modern computers. The BITMAP ENABLE allows you to op-
timize the use of resources by choosing the graphics mode best suited
to the needs of the program and, at the same time, to generalize if the
program must be ported on other hardware.

Given the great variety of hardware that ugBASIC supports and the
isomorphic approach adopted, this commands can be used to require a
specific resolution, color depth and other characteristics in a hardware
independent way.
In this regard, the following approach has been adopted. It is possi-
ble to ask for specific chacteristics, such as height and width of the
screen. However ugBASIC will choose the closest resolution, based on
the hardware on which it will runs.
Likewise, if no type of resolution constraint is set, the best is offered.
To change resolution and colors, you can use the ([width],[height],[colors]),

290
 15.46 BITMAP ENABLE

([width],[height]) or the ([colors]) syntax after BITMAP ENABLE

command. So, if you omit a parameters, it means thatit is not impor-
tant to set.
See also BITMAP DISABLE, TILEMAP ENABLE

Abbreviated as BmEn
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3 d32 d64 mo5 pc128op
plus4 to8

EXAMPLES
1 BITMAP ENABLE
2 BITMAP ENABLE (320 ,200 ,16)
3 BITMAP ENABLE (160 ,200 ,2)

291
 15 Keywords

15.47 BLACK (constant)

SYNTAX
= BLACK

PURPOSE
This keyword represents the color black. Depending on the methodology
and technique, as well as the available hardware, it can correspond to
a specific color in the RGB space, usually (0,0,0). However, not all
computers have this color. In which case, it is approximated by the
closest color available, which is usually also used in decoding images to
identify the color to use.
Abbreviated as Bl

EXAMPLES
1 PEN BLACK

292
 15.48 BLIT (data type)

15.48 BLIT (data type)

SYNTAX
... AS BLIT

PURPOSE
This data type holds a reference to the blitting operation. It can be used
as an argument to the blitting instruction, to specify how to manipulate
the input channels.

See also BLIT (instruction), BLIT IMAGE

Abbreviated as Blt
EXAMPLES
1 DIM x AS BLIT

293
 15 Keywords

15.49 BLIT (instruction)

SYNTAX
BLIT identifier AS expression

PURPOSE
The “BLITTING” is a data operation used in computer graphics in
which several bitmaps are combined into one using a boolean (or math-
ematical) function. The operation involves at least two bitmaps: a
“source” (or “foreground”) and a “destination” (or “background”), and
other fields, called “masks” or something like that. The result may be
written to a final bitmap, though often it replaces the “destination”
field.
The pixels of each are combined bitwise according to the specified BLIT
OPERATION (BOP) and the result is then written to the destination.
The BOP is essentially a boolean formula, that can be written using
BLIT instructrion. The most obvious BOP overwrites the destination
with the source. Other BOPs may involve AND, OR, XOR, and other more
complex operations.

See also BLIT (data type), BLIT IMAGE

Abbreviated as Blt
EXAMPLES
1 BLIT bop1 AS ( ( SOURCE ) AND ( DESTINATION ) )

294
 15.50 BLIT IMAGE

15.50 BLIT IMAGE

SYNTAX
BLIT IMAGE i1, i2, ... AT [x], [y] WITH b
BLIT IMAGE i1, i2, ... FRAME frame AT [x], [y] WITH b
BLIT IMAGE i1, i2, ... STRIP s FRAME f AT [x], [y] WITH b

PURPOSE

The “BLITTING” is a data operation used in computer graphics in

which several bitmaps are combined into one using a boolean (or math-
ematical) function. The operation involves at least two bitmaps: a
“source” (or “foreground”) and a “destination” (or “background”), and
other fields, called “masks” or something like that. The result may be
written to a final bitmap, though often it replaces the “destination”
field.
To draw, the BLIT IMAGE(S) command will be used. The syntax of
this command will be identical to that of PUT IMAGE (therefore with
management of images and sequences), with two main differences. The
first is the ability to indicate multiple images (separated from each other
by a comma) and the second is to be able to indicate which blitting
operation you want to use.
See also BLIT (data type), BLIT (instruction)
Abbreviated as BltIm

EXAMPLES
1 BLIT IMAGE test AT 0 , 0 WITH bop

295
 15 Keywords

15.51 BLOCK

SYNTAX
BLOCK x1, y1, x2, y2, fq

PURPOSE
Alias for BAR
Abbreviated as Blk

EXAMPLES
1 BLOCK x , y , x +29 , y +19 , 0

296
 15.52 BLUE (constant)

15.52 BLUE (constant)

SYNTAX
= BLUE

PURPOSE
This keyword represents the color blue. Depending on the methodology
and technique, as well as the available hardware, it can correspond to
a specific color in the RGB space, usually (0,0,170). However, not
all computers have this color. In which case, it is approximated by the
closest color available, which is usually also used in decoding images to
identify the color to use.
Abbreviated as Bu

EXAMPLES
1 PEN BLUE

297
 15 Keywords

15.53 BOOM

SYNTAX
BOOM [duration [MS]] [ON channel]

PURPOSE
This command makes the computer emit an explosion-like sound. It is
possible to indicate the duration of sound effect and on which voices
the system should emit the sound. If omitted, it will be issued on all.

Note that the execution of the effect can be synchronous or asyn-

chronous, depending on the target. Synchronous execution means that
the program will wait for the effect to complete before returning; on
the contrary, asynchronous execution requires the program to continue
executing subsequent instructions.

The behavior can be modified by the DEFINE AUDIO SYNC and DEFINE
AUDIO ASYNC pragmas, which however may not be available for the
target in question.
Abbreviated as Boo

AVAILABLE ON
atari atarixl c128 c64 coleco cpc msx1 plus4 vg5000 vic20
EXAMPLES
1 BOOM 1000 MS
2 BOOM 100 MS ON %001

298
 15.54 BORDER

15.54 BORDER

SYNTAX
BORDER shade

PURPOSE
Alias for COLOR BORDER.
Alias for COLOR BORDER

Abbreviated as Bo

299
 15 Keywords

15.55 BOX

SYNTAX
BOX [x1], [y1] TO x2, y2[, c ]
BOX TO x2, y2[, c ]

PURPOSE
This instruction draws a rectangle on the screen, starting from the
coordinates (x1, y1) to arrive at the coordinates (x2, y2), using the
color c. The start coordinates can be omitted: in this case, ugBASIC
will draw starting from the last drawn position. If the color is omitted,
the last color selected with the INK or PEN command will be used.
Finally, the default line style is full but a 16 bit bitmask can be set with
the SET LINE command.

Alias for REC

Abbreviated as Bx
EXAMPLES
1 BOX 10 ,10 TO 100 ,100 , WHITE
2 BOX TO 100 ,100
3 BOX ,10 TO ,100

300
 15.56 BROWN (constant)

15.56 BROWN (constant)

SYNTAX
= BROWN

PURPOSE
This keyword represents the color brown. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (221, 136, 101). How-
ever, not all computers have this color. In which case, it is approximated
by the closest color available, which is usually also used in decoding im-
ages to identify the color to use.
Abbreviated as Brn

EXAMPLES
1 PEN BROWN

301
 15 Keywords

15.57 BUFFER (data type)

SYNTAX
... AS BUFFER

PURPOSE
This data type holds a reference to any generic buffer, that is a memory
area of any kind, from a spare memory to a specific and big resource.

Abbreviated as Bf
EXAMPLES
1 DIM x AS BUFFER

302
 15.58 BYTE (data type)

15.58 BYTE (data type)

SYNTAX
... AS BYTE

PURPOSE
The BYTE represent the data type for 8 bit numbers. This kind of data
can represent a single character, such as a letter or number, could be
represented with a byte, integers between 0 and 255 could be repre-
sented directly in a byte.
Abbreviated as By
EXAMPLES
1 DIM x AS BYTE

303
15 Keywords

15.59 CALL

SYNTAX
CALL name
CALL name parameters "[" [par1 [, par2[, ...]]] "]"

PURPOSE
The CALL command is used to call a previously defined procedure (or
subroutine) within the same program. A procedure is a separate block
of code designed to perform a specific task. By using CALL, you can
execute the code within the procedure multiple times, without having
to rewrite the same statements each time.
Before you can call a procedure, you must define it. In ugBASIC, a
procedure is typically defined with the PROCEDURE keyword followed
by the name of the procedure. Inside the procedure, you write the
statements that should be executed when the procedure is called.
To execute the code within the procedure, you use the CALL command
followed by the name of the procedure.
When the program reaches this line, control is transferred to the first
statement in the procedure. Once all the statements in the procedure
are executed, control returns to the line after CALL.
Dividing a program into procedures makes the code more organized
and easier to read, and a procedure can be called multiple times from
different parts of the program, avoiding code duplication. Procedures
can be used to break a complex problem into simpler subproblems, that
helps to create a hierarchical structure in the program.
You can also pass arguments to a procedure, enclosed in square param-
eters: arguments are values that are passed to the procedure when it is
called and that can be used within the procedure itself. If the procedure

304
 15.59 CALL

returns a value, the calling statement just ignore it.

By breaking code into procedures, it becomes easier to understand and
maintain, and by reusing the same procedures in multiple parts of the
program, you reduce the chances of introducing errors. Finally, if you
need to change one part of the code, you can simply change the cor-
responding procedure, without having to make changes in all the parts
of the program that use that part of the code.
Important: if the OPTION CALL AS GOTO pragma is in effect, the in-
struction will be considered as a GOTO rather than a GOSUB. So, no
return value and no return, at all. This not applies to system calls.
Abbreviated as Ca
EXAMPLES
1 CALL factorial [42]

305
 15 Keywords

15.60 CAN SCREEN

SYNTAX
= CAN SCREEN mode

PURPOSE
This instruction allows you to check if a certain screen mode is available
or not. If that mode is available, the instruction will return the value
TRUE. Otherwise, the statement will return FALSE.

D
Abbreviated as CnSc

E
EXAMPLES AT
1 IF CAN SCREEN 2 THEN : PRINT " mode 2 is available ": ENDIF
EC
PR
DE

306
 15.61 CAPS LOCK (constant)

15.61 CAPS LOCK (constant)

SYNTAX
= CAPS LOCK

PURPOSE
This constant represent the ”CAPS LOCK” key, when used as bitmask
for KEY SHIFT instruction.

Alias for CAPSLOCK (constant)

Abbreviated as CpLk
EXAMPLES
1 IF KEY SHIFT AND CAPS LOCK THEN
2 PRINT " CAPS LOCK has been pressed !"
3 ENDIF

307
 15 Keywords

15.62 CAPSLOCK (constant)

SYNTAX
= CAPSLOCK

PURPOSE
Alias for CAPS LOCK (constant)
Abbreviated as CAPSLOCK

EXAMPLES
1 IF KEY SHIFT AND CAPSLOCK THEN
2 PRINT " CAPS LOCK has been pressed !"
3 ENDIF

308
 15.63 CASE

15.63 CASE

SYNTAX
CASE value

PURPOSE
The CASE command is part of SELECT...ENDSELECT construct. Each
CASE represents a possible value of the expression. After each case,
you can insert the statements that will be executed if the value of the
expression matches that case. The code will be executed up to the
ENDSELECT instruction, another CASE instruction and, finally, when a
CASE ELSE is matched.
See also SELECT CASE, CASE ELSE, ENDSELECT

Abbreviated as Cs
EXAMPLES
1 SELECT CASE answer
2 CASE 42
3 PRINT " The answer !"
4 CASE ELSE
5 PRINT " I am still thinking ..."
6 ENDSELECT

309
 15 Keywords

15.64 CASE ELSE

SYNTAX
CASE ELSE

PURPOSE
The CASE ELSE command is part of SELECT...ENDSELECT construct.
It is optional and is executed if none of the previous cases are true. The
code will be executed up to the ENDSELECT instruction.

See also SELECT CASE, CASE, ENDSELECT

Abbreviated as CsEl
EXAMPLES
1 SELECT CASE answer
2 CASE 42
3 PRINT " The answer !"
4 CASE ELSE
5 PRINT " I am still thinking ..."
6 ENDSELECT

310
 15.65 CDOWN (function)

15.65 CDOWN (function)

SYNTAX
CDOWN$

PURPOSE
The effect of summoning up the special control character CDOWN$ is
exactly the same as printing after a CDOWN command. The advantage of
this alternative is that several text cursor movements can be combined
in a single string, using CDOWN$.
See also CMOVE$, CUP$, CDOWN, CLEFT$, CRIGHT$
Abbreviated as Cd
EXAMPLES
1 PRINT CDOWN$

311
 15 Keywords

15.66 CDOWN (instruction)

SYNTAX
CDOWN

PURPOSE
By using the CDOWN command you can force the text cursor down a
single line.

See also CMOVE, CUP, CDOWN$, CLEFT, CRIGHT

Abbreviated as Cd
EXAMPLES
1 CDOWN

312
 15.67 CENTER

15.67 CENTER

SYNTAX
CENTER text [;]

PURPOSE
The CENTER command aligns a text string in the center of a line. In
other words, it allows you to position a word or phrase so that it occupies
the available space in a symmetrical manner. The CENTER command
calculates the white space needed on the sides of the string to center
it within the specified width and adds the necessary spaces. If the
statement is followed by a semicolon, the cursor will remain on the
same line. Otherwise, it will move to the next line.
This command can be used to create aesthetically pleasing section or
chapter titles, to center menu options in the center of the console and
to format data neatly in a report. Centered text is easier to read and
makes programs look neater.
By using CENTER, you can ensure that text is aligned uniformly in
different parts of the program, and on different targets. Moreover,
reduce the need to manually calculate character positions.
Alias for CENTRE
Abbreviated as Ce
EXAMPLES
1 CENTER " HELLO !"
2 CENTER " HELLO !";

313
 15 Keywords

15.68 CENTRE

SYNTAX
CENTRE text [;]

PURPOSE
Alias for CENTER
EXAMPLES
1 CENTRE " HELLO !"
2 CENTRE " HELLO !";

314
 15.69 CGOTO

15.69 CGOTO

SYNTAX
CGOTO expression

PURPOSE
Calculate the number of the line to which the program execution must
pass. Allows you to jump to a variable program line number, determined
by the result of a calculation. CGOTO is a command that replaces long
jump tables behind the BASIC command ON.
Instead of specifying the jump targets as with ON and then calling them
by specifying the location number of the desired target, the desired tar-
get line can be targeted immediately by calculation after CGOTO without
much typing.

The use of CGOTO requires that the lines are arranged in such a way
when programming that these lines remain accessible for the algorithm
expression behind CGOTO.
Abbreviated as Cg

EXAMPLES
1 CGOTO 10* i +100

315
15 Keywords

15.70 CHARSET AT

SYNTAX
PURPOSE

Abbreviated as CHARSETAt
AVAILABLE ON
atari c64 plus4

316
 15.71 CHR$

15.71 CHR$

SYNTAX

= CHR$(value)

PURPOSE
The CHR$ function converts a numeric code (usually an integer) into a
corresponding character. In other words, it takes a number and returns
the character associated with that number in the ASCII table.
You can combine multiple CHR$ to create strings of specific characters,
and insert special characters, such as control characters or non-printing
characters, using their ASCII codes. In some applications, CHR$ can be
used to encode or decode information, because ASCII table associates
a unique number with each character used in computers. The first 32
codes (0 through 31) represent control characters, such as the new-
line character or tabulator. Codes 32 through 127 represent printable
characters, such as letters, numbers, and symbols.

See also ASC

EXAMPLES
1 x = CHR$ (65)

317
 15 Keywords

15.72 CIRCLE

SYNTAX
CIRCLE [x], [y], r[, c]
CIRCLE x, y, rx, ry[, c]

PURPOSE
The CIRCLE command in BASIC draws a circle on the screen. In other
words, it defines a complete circle based on the coordinates and radius
that you specify.
This command allows you to draw a circle with starting coordinates in
(x,y) and radius r. The color is indicated by the parameter c. If the
abscissa and/or ordinate is omitted, the last graphic position drawn will
be used. In addition, the color can also be omitted and, if necessary,
the last color set with the PEN or INK command will be used.
There is also another additional syntax, that can be used to draw el-
lipses: you can give both the radii rx and ry in the color determined
by fq (see HIRES).

The accuracy of the circle depends on the resolution of your screen.

Lower-resolution screens may display less sharp circles.
See also ELLIPSE
Abbreviated as Ci

EXAMPLES
1 ’ Draw a circle
2 CIRCLE 100 ,100 ,42
3 ’ Draw an ellipse
4 CIRCLE 100 ,100 ,21 ,42
5 CIRCLE , ,21 , RED

318
 15.73 CLEAR

15.73 CLEAR

SYNTAX
CLEAR size

PURPOSE
The CLEAR command serves two purposes: when CLEAR is executed,
all numeric variables are initialized to zero and all strings are set to
the empty string (””). This is especially useful at the beginning of
a program to ensure that there are no residual values from previous
executions. It can be used to resize (statically) allocated memory for
dynamic strings. This may be necessary to avoid ”out of memory”
errors when working with strings.
Abbreviated as Clr

EXAMPLES
1 CLEAR 2048

319
 15 Keywords

15.74 CLEAR (constant)

SYNTAX
= CLEAR

PURPOSE
This constant represent the ”CLEAR” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Clr
EXAMPLES
1 IF KET STATE ( CLEAR ) THEN
2 PRINT " CLEAR has been pressed !"
3 ENDIF

320
 15.75 CLEFT (function)

15.75 CLEFT (function)

SYNTAX
CLEFT$

PURPOSE
The effect of summoning up the special control character CLEFT$ is
exactly the same as printing after a CLEFT command. The advantage of
this alternative is that several text cursor movements can be combined
in a single string, using CLEFT$.
See also CMOVE$, CUP$, CDOWN$, CLEFT, CRIGHT$
Abbreviated as Cle
EXAMPLES
1 PRINT CCLEFTUP$

321
 15 Keywords

15.76 CLEFT (instruction)

SYNTAX
CLEFT

PURPOSE
By using the CLEFT command you can force the text cursor left by a
single character.

See also CMOVE, CUP, CDOWN, CLEFT$, CRIGHT

Abbreviated as Cle
EXAMPLES
1 CLEFT

322
 15.77 CLINE

15.77 CLINE

SYNTAX
CLINE [chars]

PURPOSE
The CLINE command is used to clear the line currently occupied by
the text cursor. If CLINE is followed by a number, then that number
of characters get cleared, starting from the current cursor position and
leaving the cursor exactly where it is.
Abbreviated as Cln
AVAILABLE ON

atari c128 c64 coco coco3 d32 d64 mo5 pc128op plus4 to8 vic20

EXAMPLES
1 CLINE
2 CLINE 20

323
 15 Keywords

15.78 CLIP

SYNTAX
CLIP x1,y1 TO x2, x2

PURPOSE
The CLIP instruction allows you to delimit the area in which the graph-
ics are actually drawn. In general, the area corresponds to the entire
surface of the screen (0,0)-(SCREEN WIDTH-1,SCREEN HEIGHT-1).
However, it is possible to limit the drawing to a sub area, to ensure that
the area outside this crop area is not altered or modified. The area is
bounded by the coordinate (x1, y1) to the coordinate (x2, y2). If
components are omitted, the screen limits will be used.
Abbreviated as Cli

EXAMPLES
1 CLIP 42 ,42 TO 84 ,84

324
 15.79 CLS

15.79 CLS

SYNTAX

CLS
CLS color

PURPOSE
The CLS command is used to clear the screen and return the cursor to
the upper left corner. In other words, CLS clears the screen, eliminating
everything that was previously printed.
Before printing new data to the screen, it is often useful to use CLS to
have a clean and tidy space. In combination with other instructions,
CLS can be used to create simple animations by erasing and redrawing
elements on the screen. It allows you to update the user interface
without leaving traces of previous operations.
The CLS command is generally very fast to execute and can also be
used in graphics mode to clear the entire drawing area. It also has
the ability to set a default background color, if possible. The clearing
occurs with respect to the selected mode, so it will be a ”pixel by pixel”
clearing (if in bitmap mode) or ”tile by tile” (if in tile mode). In the
second case, the value of the EMPTYTILE variable will be used, possibly
overridden
Alias for PCLS

Abbreviated as Cl
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc d32 d64 msx1 pc128op
plus4 sc3000 sg1000 to8 vg5000 vic20 zx

325
 15 Keywords

EXAMPLES
1 CLS
2 CLS WHITE

326
 15.80 CMOB

15.80 CMOB

SYNTAX
CMOB c1, c2

PURPOSE
The CMOB instruction attribute the two colors that are the same for
all multicolor sprites in VIC-II registers. Color for individual sprites are
available with the MOB SET command or, even, MOBCOL.

Abbreviated as Cmo
EXAMPLES
1 CMOB RED , BLUE

327
 15 Keywords

15.81 CMOVE (function)

SYNTAX
= CMOVE$( x, y )

PURPOSE
The CMOVE$ function can be used to generate a string that moves
the text cursor a pre-set distance away from its current position. The
command is followed by a pair of variables that represent the width
and height of the required offset, and these values are added to the
current cursor coordinates. Like LOCATE, either of the coordinates can
be omitted, as long as the comma is positioned correctly. An additional
technique is to use negative values as well as positive offsets.
See also CMOVE (instruction)

Abbreviated as Cm
EXAMPLES
1 PRINT CMOVE$ (10 ,10)

328
 15.82 CMOVE (instruction)

15.82 CMOVE (instruction)

SYNTAX
CMOVE [dx], [dy]

PURPOSE
CMOVE allows to move the text cursor a pre-set distance away from its
current position. The command is followed by a pair of variables that
represent the width and height of the required offset, and these values
are added to the current cursor coordinates. Like LOCATE, either of
the coordinates can be omitted, as long as the comma is positioned
correctly. An additional technique is to use negative values as well as
positive offsets.
See also CMOVE (function)

Abbreviated as Cm
EXAMPLES
1 CMOVE -1 , -1
2 CMOVE 4 ,

329
 15 Keywords

15.83 COLLISION

SYNTAX
= COLLISION(sprite)

PURPOSE
Verify if a sprite has had a collision with another sprite. If the sprite
has collided, the function will return TRUE. Otherwise, it will return
FALSE.

Alias for HIT

Abbreviated as Col
AVAILABLE ON

c128 c64
EXAMPLES
1 x = COLLISION (1)

330
 15.84 COLOR

15.84 COLOR

SYNTAX
COLOR index, shade
COLOR border, background, foreground
COLOR [border,][background] (if TSB is enabled)
COLOR border
COLOR ,foreground

PURPOSE
The COLOR command allows you to redefine the colors used by the
graphics chipset, where this is possible. ”Redefinition” means assigning
one of the possible colors to specific registers called ”palette registers”.
On some systems this is not possible at all, due to limitations of the
chipset or the absence of registers: for this reason, in such cases the
command is ignored. On other systems this corresponds to the mod-
ification of specific registers, to which one of the available colors is
assigned. On others it is possible to assign certain shades, which there-
fore go beyond the number of available colors.

Where it is possible to assign a shade, the value can range from 0 to

the constant SHADES. However, it may be more practical to use the
RGB function, which allows you to calculate the shade starting from the
color components (red, green and blue).
If compatibility with Tuned Simons’ BASIC is active, the semantics of
the command changes, to directly indicate some specific components
through a series of syntax variants. With the three-parameter variant,
you can directly set the colors of the border, background and text. With
the two-parameter variant, it will be possible to indicate the border and
the background. With a single parameter, it will be possible to indicate
the color of the border only. There is also the format where the first

331
 15 Keywords

parameter is omitted, in which case the second indicates the color of

the text.
Note that the syntax with one or three parameters is automatically
considered as pertaining to TSB.

Alias for COLOUR

See also COLOR BORDER, SHADES (constant), RGB
Abbreviated as Cr

AVAILABLE ON
atari atarixl c128 c128z c64 c64reu coco coco3 cpc d32 d64
mo5 pc128op plus4 to8 vic20
EXAMPLES
1 COLOR 0 , $fff

332
 15.85 COLOR (data type)

15.85 COLOR (data type)

SYNTAX
DIM c AS COLOR
x = (COLOR) 42

PURPOSE
The COLOR data type holds enough information to represent a color on
the target’s video chipset. This type of information allows one of several
possible colors to be selected, either predefined or redefined, depending
on the targets’ capabilities.
Abbreviated as Cr

333
 15 Keywords

15.86 COLOR (function)

SYNTAX
= COLOR(index)

PURPOSE
This function allows you to retrieve the color associated with the indi-
cated position. Depending on the video chipset considered, the param-
eter of this function can be the number of possible colors or a specific
register. Furthermore, the information returned is of type COLOR, so it
can be used where it is necessary to indicate a color.
Note that this function does not necessarily return information on the
”shade”, but the result can be compared with the predefined constants.

Abbreviated as Cr
AVAILABLE ON
atari atarixl c128 c128z c64 c64reu coco coco3 coleco cpc d32
d64 mo5 msx1 pc128op plus4 sc3000 sg1000 to8 vic20 zx

EXAMPLES
1 c = COLOR (0)

334
 15.87 COLOR BACK

15.87 COLOR BACK

SYNTAX
COLOR BACK color

PURPOSE
The COLOR BACK command used on target that support both color
graphics, backgorund colors and specialized clearing screen routines.
Its primary function is to set the background color of the screen or a
specific area of the screen, and then clearing the screen using that color.
This command can be used to customize the appearance of programs
by creating colored backgrounds, and could be essential for creating
simple games or graphical applications, where the background color
contributes to aesthetics and readability. This can be used to highlight
certain areas of the screen or to create visual contrasts.
The availability of colors and the accuracy of their representation depend
on the computer’s video chipsed.
See also PAPER, CLS

Abbreviated as CrBa
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc d32 d64 mo5 msx1
pc128op plus4 sc3000 sg1000 to8 vg5000 vic20 zx

EXAMPLES
1 COLOR BACK RED
2 COLOR BACK WHITE

335
15 Keywords

15.88 COLOR BACKGROUND

SYNTAX
COLOR BACKGROUND value
COLOR BACKGROUND index TO value

PURPOSE
The COLOR BACKGROUND command allows you to redefine the color used
by the graphics chipset for the background, where this is possible. ”Re-
definition” means assigning one of the possible colors to specific regis-
ters called ”palette registers”.
On some systems this is not possible at all, due to limitations of the
chipset or the absence of registers: for this reason, in such cases the
command is ignored. On other systems this corresponds to the mod-
ification of specific registers, to which one of the available colors is
assigned. On others it is possible to assign certain shades, which there-
fore go beyond the number of available colors.
Where it is possible to assign a shade, the value can range from 0 to
the constant SHADES. However, it may be more practical to use the
RGB function, which allows you to calculate the shade starting from the
color components (red, green and blue).
See also COLOR, SHADES (constant), RGB
Abbreviated as CrBg

AVAILABLE ON
atari c128 c64 plus4 vic20

336
 15.89 COLOR BORDER

15.89 COLOR BORDER

SYNTAX
COLOR BORDER value

PURPOSE
The COLOR BORDER command allows you to redefine the color used by
the graphics chipset for the border, where this is possible. ”Redefini-
tion” means assigning one of the possible colors to specific registers
called ”palette registers”.
On some systems this is not possible at all, due to limitations of the
chipset or the absence of registers or even of the border: for this rea-
son, in such cases the command is ignored. On other systems this
corresponds to the modification of specific registers, to which one of
the available colors is assigned. On others it is possible to assign certain
shades, which therefore go beyond the number of available colors.
Where it is possible to assign a shade, the value can range from 0 to
the constant SHADES. However, it may be more practical to use the
RGB function, which allows you to calculate the shade starting from the
color components (red, green and blue).

Alias for BORDER

See also COLOR, SHADES (constant), RGB
Abbreviated as CrBo

AVAILABLE ON
atari c128 c128z c64 c64reu coco coco3 coleco cpc mo5 msx1
pc128op plus4 sc3000 sg1000 to8 vic20 zx
EXAMPLES

337
 15 Keywords

1 COLOR BORDER # $1

338
 15.90 COLOR COUNT (constant)

15.90 COLOR COUNT (constant)

SYNTAX
= COLOR COUNT

PURPOSE
Alias for COLORS.
Alias for COLORS (constant), SCREEN COLORS (constant), COLORS
COUNT (constant)
Abbreviated as CrC%

339
 15 Keywords

15.91 COLOR SPRITE

SYNTAX
COLOR SPRITE index TO color

PURPOSE
The COLOR SPRITE command allows you to redefine the (common)
colors used by the graphics chipset for the sprites, where this is possible
and/or they are available. ”Redefinition” means assigning one of the
possible colors to specific registers called ”palette registers”.
On some systems this is not possible at all, due to limitations of the
chipset or the absence of registers or even of the sprites: for this rea-
son, in such cases the command is ignored. On other systems this
corresponds to the modification of specific registers, to which one of
the available colors is assigned. On others it is possible to assign certain
shades, which therefore go beyond the number of available colors.
Where it is possible to assign a shade, the value can range from 0 to
the constant SHADES. However, it may be more practical to use the
RGB function, which allows you to calculate the shade starting from the
color components (red, green and blue).
See also SHADES (constant), RGB
Abbreviated as CrSpr
AVAILABLE ON

c128 c64 c64reu

EXAMPLES
1 COLOR SPRITE 1 TO YELLOW

340
 15.92 COLORMAP AT

15.92 COLORMAP AT

SYNTAX
COLORMAP AT #address

PURPOSE
Set the starting address, in memory, for the colormap. The input pa-
rameter is decoded and declined according to the hardware limits. So
it is not said that exactly the given address is set.

See also BITMAP ENABLE

Abbreviated as COLORMAPAt
AVAILABLE ON

c128 c64 plus4

EXAMPLES
1 COLORMAP AT # $B800

341
 15 Keywords

15.93 COLORMAP CLEAR

SYNTAX
COLORMAP CLEAR WITH #fore ON #back
COLORMAP CLEAR WITH fore ON back
COLORMAP CLEAR

PURPOSE

Erase the entire color map, using a foreground and a background color.
See also BITMAP ENABLE
Abbreviated as COLORMAPClr
AVAILABLE ON

c128 c64 coco coco3 d32 d64 mo5 pc128op plus4 to8 vic20
EXAMPLES
1 COLORMAP CLEAR WITH # $0 ON # $1
2 COLORMAP CLEAR WITH YELLOW ON RED
3 COLORMAP CLEAR

342
 15.94 COLORS (constant)

15.94 COLORS (constant)

SYNTAX
= COLORS

PURPOSE
This constant holds the maximum number of colors available for the
target, for the current mode. Note that, although this is the number
of colors available, it is not guaranteed that every single graphic or text
element in the mode could assume this number independently. This
depends on the specific characteristics of the video chipset available.
Also, it is not guaranteed that the colors are changeable. This infor-
mation is useful when you want to choose a random color from those
available, or to perform loops on the actual availability of colors.

Alias for SCREEN COLORS (constant), COLORS COUNT (constant),

COLOR COUNT (constant)
Abbreviated as Crs

343
15 Keywords

15.95 COLORS COUNT (constant)

SYNTAX
= COLORS COUNT

PURPOSE
Alias for COLORS.
Alias for COLORS (constant), SCREEN COLORS (constant), COLOR
COUNT (constant)
Abbreviated as CrsC%

344
 15.96 COLOUR

15.96 COLOUR

SYNTAX
COLOUR index, shade

PURPOSE
Alias for COLOR.
Alias for COLOR

See also SHADES (constant), RGB

AVAILABLE ON
atari atarixl c128 c128z c64 coco coco3 cpc d32 d64 mo5 pc128
plus4 to8 vic20

EXAMPLES
1 COLOUR 0 , $fff

345
15 Keywords

15.97 COLOURS (constant)

SYNTAX
= COLOURS

PURPOSE
Alias for COLORS.
Alias for SCREEN COLOURS (constant), COLOURS COUNT (constant)

Abbreviated as COLOURS

346
 15.98 COLOURS COUNT (constant)

15.98 COLOURS COUNT (constant)

SYNTAX
= COLOURS COUNT

PURPOSE
Alias for COLORS.
Alias for COLOURS (constant), SCREEN COLOURS (constant)

Abbreviated as COLOURSC%

347
15 Keywords

15.99 COLUMNS (constant)

SYNTAX
= COLUMNS

PURPOSE
This constant represents the number of columns present in the last
defined console.

See also SCREEN COLUMNS (constant)

Abbreviated as Cms

348
 15.100 COMBINE NIBBLE

15.100 COMBINE NIBBLE

SYNTAX
= COMBINE NIBBLE( value1, value2 )

PURPOSE
The command COMBINE NIBBLE allows you to combine two variables
that contains a 4 bit value (nibble) into a single 8 bit value. The first
value is the high nibble.

Abbreviated as CmbNi
EXAMPLES
1 b = COMBINE NIBBLE ( 8 , 8 )

349
15 Keywords

15.101 CONFIGURE

SYNTAX
CONFIGURE STATIC hw SET p1 = v1 [, p2 = v2 [, ...]]
CONFIGURE DYNAMIC hw SET p1 = v1 [, p2 = v2 [, ...]]

PURPOSE
The CONFIGURE command allow to customize hardware configuration,
and gives the possibility of generating hardware selection menus via soft-
ware. The configuration allows two types of manipulation: a STATIC
one, which is adopted at compilation time (useful for development and
unconventional startup) and a DYNAMIC one, which is adopted at execu-
tion time (useful for creating configuration menus). Static changes must
begin with the CONFIGURE STATIC keywords, while dynamic changes
must begin with the CONFIGURE DYNAMIC keywords. By default, the
changes are to be considered static.
Each hardware change request must begin with the CONFIGURE keyword
followed by the name of the hardware to be configured. Each request for
hardware modification must concern one or more parameters prefixed
by the SET command. The value that can be assigned to these variables
must be consistent with the expected and acceptable values.
Finally, it is possbile to assign multiple values consecutively, separating
them with a comma, without using the SET command.
Abbreviated as Cfg

350
 15.102 CONSOLE

15.102 CONSOLE

SYNTAX
CONSOLE x1, y1 TO x2, y2

PURPOSE
The CONSOLE command allows you to define an area of the screen where
the text output will take place. This area can be defined in both text
and graphical mode. Normally, it is set to the entire screen surface,
but can be limited with this command. This command works only with
texts. The parameters describe the four vertices.
Note that the number of rows (ROWS) and columns (COLUMNS) will be
updated conseguently. If you need the screen rows and columns, you
need to use SCREEN ROWS and SCREEN COLUMNS.

Abbreviated as Cns
EXAMPLES
1 CONSOLE 0 ,0 , SCREEN COLUMNS -1 ,2

351
 15 Keywords

15.103 CONSOLE RESTORE

SYNTAX
CONSOLE RESTORE number

PURPOSE
The command CONSOLE RESTORE allows you to restore the constraints
of the given console, previously saved with the command CONSOLE
SAVE.

Abbreviated as CnsRer
EXAMPLES
1 CONSOLE RESTORE 2

352
 15.104 CONSOLE SAVE

15.104 CONSOLE SAVE

SYNTAX
CONSOLE SAVE number

PURPOSE
The command CONSOLE SAVE allows you to save the constraints of the
given console.

Abbreviated as CnsSv
EXAMPLES
1 CONSOLE SAVE 2

353
 15 Keywords

15.105 CONSOLE USE

SYNTAX
CONSOLE USE number

PURPOSE
Alias for CONSOLE RESTORE.
Abbreviated as CnsUx

EXAMPLES
1 CONSOLE USE 2

354
 15.106 CONST

15.106 CONST

SYNTAX
[POSITIVE] CONST identifier = value
CONST identifier IN (min,max) = value
CONST identifier IN "[" min,max) = value
CONST identifier IN (min,max "]" = value
CONST identifier IN "[" min,max "]"" = value

PURPOSE
Using the CONST command allows you to define one or more constants,
which will be used later in the program. Constants have the advantage
of being calculated once and for all, at compile time, directly by the
compiler and can be used to initialize variables. Furthermore, the con-
stants are global, that is, they are always visible everywhere, both in
the main program and within the procedures. Finally, constants do not
take up memory space.
In the definition of the constants itself it is possible to indicate whether
it must be positive or not, with the keyword POSITIVE. This check is
carried out at compilation time and, in the event of a negative result, it
will result in a compilation error. This condition is useful to ensure that
the preconditions related to the hardware are respected (as happens, for
example, when calculating the margins in the case of a screen smaller
than the expected minimum).
It is also possible to define a validity range of the values that will be
represented in the constant. This interval is defined in a similar way
to intervals in mathematics: using the square bracket means that the
extremes (minimum, maximum) are included, while a round bracket
means that the extremes are excluded.
Alias for SHARED CONST, CONST SHARED, GLOBAL CONST, CONST GLOBAL

355
 15 Keywords

Abbreviated as C#
EXAMPLES
1 CONST x = 42
2 POSITIVE CONST y = -42: ’ this raises an error !
3 CONST width IN (0 ,320] = 128

356
 15.107 CONST GLOBAL

15.107 CONST GLOBAL

SYNTAX
[POSITIVE] CONST GLOBAL identifier = value
CONST GLOBAL identifier IN (min,max) = value
CONST GLOBAL identifier IN "[" min,max) = value
CONST GLOBAL identifier IN (min,max "]" = value
CONST GLOBAL identifier IN "[" min,max "]"" = value

PURPOSE
Alias for SHARED, CONST SHARED, SHARED CONST, GLOBAL CONST
Abbreviated as C#Gb
EXAMPLES
1 CONST GLOBAL x = 42
2 POSITIVE CONST GLOBAL y = -42: ’ this raises an error !
3 CONST GLOBAL width IN (0 ,320] = 128

357
 15 Keywords

15.108 CONST SHARED

SYNTAX
[POSITIVE] CONST SHARED identifier = value
CONST SHARED identifier IN (min,max) = value
CONST SHARED identifier IN "[" min,max) = value
CONST SHARED identifier IN (min,max "]" = value
CONST SHARED identifier IN "[" min,max "]"" = value

PURPOSE
Alias for SHARED CONST, SHARED, GLOBAL CONST, CONST GLOBAL
Abbreviated as C#Sr
EXAMPLES
1 CONST SHARED x = 42
2 POSITIVE CONST SHARED y = -42: ’ this raises an error !
3 CONST SHARED width IN (0 ,320] = 128

358
 15.109 CONTROL (constant)

15.109 CONTROL (constant)

SYNTAX
= CONTROL

PURPOSE
This constant represent the ”CONTROL” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Ctrl
EXAMPLES
1 IF KET STATE ( CONTROL ) THEN
2 PRINT " CONTROL has been pressed !"
3 ENDIF

359
 15 Keywords

15.110 COS

SYNTAX
= COS(angle)

PURPOSE
This function will calculate the cosine value of an angle. The cosine
of an acute angle are defined in the context of a right triangle: for the
specified angle, its sine is the ratio of the length of the side that is
opposite that angle to the length of the longest side of the triangle (the
hypotenuse), and the cosine is the ratio of the length of the adjacent
leg to that of the hypotenuse.
More generally, the definitions of sine can be extended to any real value
in terms of the lengths of certain line segments in a unit circle.

The cosine functions are commonly used to model periodic phenomena

such as sound and light waves, the position and velocity of harmonic
oscillators, sunlight intensity and day length, and average temperature
variations throughout the year.

Abbreviated as Cx
EXAMPLES
1 x = COS ( PI /2)

360
 15.111 CREATE PORT

15.111 CREATE PORT

SYNTAX
= CREATE PORT( sessionId, application )

PURPOSE
The CREATE PORT function create a message port where receive mes-
sages. The sessionId parameter is the same one that returned the
call to LOGIN function, and identifies the working session at that mo-
ment. The application parameter represents, instead, the name of
the application or functionality with which you want to associate this
message port.
The message port (mailbox) is owned by the user but also by each indi-
vidual application or application functionality. Therefore, it is possible
to define more than one mailbox (i.e., a port) for a single user, as long
as each of them is identified by a different application code.
Alias for DOJO CREATE PORT
Abbreviated as CrtPrt

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = CREATE PORT ( sessionId , " testApp " )

361
 15 Keywords

15.112 CRIGHT (function)

SYNTAX
CRIGHT$

PURPOSE
The effect of summoning up the special control character CRIGHT$ is
exactly the same as printing after a CRIGHT command. The advan-
tage of this alternative is that several text cursor movements can be
combined in a single string, using CRIGHT$.
See also CMOVE$, CUP$, CDOWN$, CLEFT, CRIGHT$
Abbreviated as Crg
EXAMPLES
1 PRINT CRIGHT$

362
 15.113 CRIGHT (instruction)

15.113 CRIGHT (instruction)

SYNTAX
CRIGHT

PURPOSE
By using the CRIGHT command you can force the text cursor right by
a single character.

See also CMOVE, CUP, CDOWN, CLEFT, CRIGHT$

Abbreviated as Crg
EXAMPLES
1 CRIGHT

363
 15 Keywords

15.114 CRSR LEFT RIGHT (constant)

SYNTAX
= CRSR LEFT RIGHT

PURPOSE
This constant represent the ”CRSR LEFT RIGHT” key, when used as a
value to compare with SCANCODE,KEY STATE and KEY PRESSED. If the
key does not exist in the corresponding target, the value will be zero.

Abbreviated as CRSRLfRg
EXAMPLES
1 IF KET STATE ( CRSR LEFT RIGHT ) THEN
2 PRINT " CRSR LEFT RIGHT has been pressed !"
3 ENDIF

364
 15.115 CRSR UP DOWN (constant)

15.115 CRSR UP DOWN (constant)

SYNTAX
= CRSR UP DOWN

PURPOSE
This constant represent the ”CRSR UP DOWN” key, when used as a
value to compare with SCANCODE,KEY STATE and KEY PRESSED. If the
key does not exist in the corresponding target, the value will be zero.

Abbreviated as CRSRUPDw
EXAMPLES
1 IF KET STATE ( CRSR UP DOWN ) THEN
2 PRINT " CRSR UP DOWN has been pressed !"
3 ENDIF

365
 15 Keywords

15.116 CSET

SYNTAX
CSET value

PURPOSE
The CSET command switches with value between the two character
sets of the VIC-II: uppercase graphics characters (0) and uppercase/low-
ercase (CSET 1). You can also use this to switch to graphics mode
without clearing the graphics memory (see HIRES), for this you use
CSET 2.
Abbreviated as Cxx
AVAILABLE ON

c128 c64 c64reu

EXAMPLES
1 CSET 1

366
 15.117 CSPRITE

15.117 CSPRITE

SYNTAX
= CSPRITE ( name flags )
= CSPRITE ( name, previous flags )

PURPOSE
This statement allows you to define a composite sprite. Composite
sprites are those sprites that are rendered by means of an overlay of
hardware sprites. The definition corresponds to the transfer of graphic
information from the graphic resource to the memory space of the ma-
chine’s hardware. In practice, it is the moment in which the sprite is
defined graphically, to be displayed.
The function accepts the name of a graphic resource, among those
previously loaded. This must correspond to a single image: therefore it
can be an image or a frame of an ATLAS or a SEQUENCE. The system,
in a completely automatic way, will convert the resource into graphic
data compatible with the sprite format, decoding each color component
with a separate sprite.
The command accepts a series of parameters, which can be added after
the name of the graphic resource. The EXPAND VERTICAL parameter
allows you to double the vertical dimensions, making each pixel oc-
cupy two or more vertical pixels. On the other hand, the COMPRESS
VERTICAL command allows you to restore the original dimensions. The
EXPAND HORIZONTAL parameter allows you to double the vertical di-
mensions, making each pixel occupy two or more vertical pixels. On
the other hand, the COMPRESS HORIZONTAL command allows you to
restore the original dimensions. Finally, it is possible to indicate one of
the colors in the palette as ”transparent”, and therefore that it does
not need to generate a hardware sprite. This can be useful where the
graphic resource does not use the color black, which is the standard

367
 15 Keywords

color to characterize the background. Due to the isomorphic nature of

the language, not all flags are usable, or have an effect, on all targets
that support sprites.
The function provides additional syntax, valid for redefining a sprite
already defined. The purpose of such syntax is to modify the graphic
information inherent to a sprite already defined previously, thus being
able to dynamically replace the appearance of the sprite. In this case,
it is necessary to provide a reference to the previously defined sprite
(previous), and ensure that the graphic characteristics (such as the
number of colors) are identical.
See also SPRITE, MSPRITE
Abbreviated as Csp
AVAILABLE ON

c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 spaceshift = CSPRITE ( LOAD IMAGE ( " spaceship . png " ) IGNORE
COLOR GREEN )
2 alien = CSPRITE ( LOAD IMAGE ( " alien1 . png " ) )
3 alien = CSPRITE ( LOAD IMAGE ( " alien2 . png " ) , alien )

368
 15.118 CUP (function)

15.118 CUP (function)

SYNTAX
CUP$

PURPOSE
The effect of summoning up the special control character CUP$ is exactly
the same as printing after a CUP command. The advantage of this
alternative is that several text cursor movements can be combined in a
single string, using CUP$.
See also CMOVE$, CUP, CDOWN$, CLEFT$, CRIGHT$
Abbreviated as Cu
EXAMPLES
1 PRINT CUP$

369
 15 Keywords

15.119 CUP (instruction)

SYNTAX
CUP

PURPOSE
By using the CUP command you can force the text cursor up a single
line.

See also CMOVE, CUP$, CDOWN, CLEFT, CRIGHT

Abbreviated as Cu
EXAMPLES
1 CUP

370
 15.120 CYAN (constant)

15.120 CYAN (constant)

SYNTAX
= CYAN

PURPOSE
This keyword represents the color cyan. Depending on the methodology
and technique, as well as the available hardware, it can correspond to a
specific color in the RGB space, usually (170,255,230). However, not
all computers have this color. In which case, it is approximated by the
closest color available, which is usually also used in decoding images to
identify the color to use.
Abbreviated as CYAN

EXAMPLES
1 PEN CYAN

371
15 Keywords

15.121 D!POKE

SYNTAX
PURPOSE

Alias for POKEW

372
 15.122 DARK BLUE (constant)

15.122 DARK BLUE (constant)

SYNTAX
= DARK BLUE

PURPOSE
This keyword represents the color dark blue. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as DkBu

EXAMPLES
1 PEN DARK BLUE

373
 15 Keywords

15.123 DARK GRAY (constant)

SYNTAX
= DARK GRAY

PURPOSE
Alias for DARK GREY (constant)
Abbreviated as DkGy

EXAMPLES
1 PEN DARK GRAY

374
 15.124 DARK GREY (constant)

15.124 DARK GREY (constant)

SYNTAX
= DARK GREY

PURPOSE
This keyword represents the color dark grey. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Alias for DARK GRAY (constant)

Abbreviated as DkGREY
EXAMPLES
1 PEN DARK GREY

375
15 Keywords

15.125 DATA

SYNTAX
DATA data1 [, data2 [, data3 ... ] ]
DATA [AS data type] data1 [, data2 [, data3 ... ] ]
DATA LOAD "filename" AS TEXT

PURPOSE
The DATA command is used to create a list of data that will be used
in other parts of the program. It is like a container where values are
stored that will then be ”read” and used by other commands.
The DATA command is usually placed at the beginning of the program or
in a section dedicated to the definitions of data, but it is not mandatory.
The data1, data2, ... so on should be replaced witht he data you want
to store inside the program. These can be numbers or text strings.
To read the data contained in a DATA statement, you use the READ
command. This command assigns the values contained in DATA to
variables.
You can use multiple DATA statements to fill an array with a set of
values. Another usage is to create small tables of data, for example to
represent menus or product lists. You can also store constants that are
used frequently in the program.
The DATA values will be read from left to right, beginning with the
first line containing a DATA statement. Each time a READ instruction
is executed the saved DATA position of the last READ is advanced to
the next value. Strings must be written in quotes, so characters like
comma, space, colon, graphical ones or control characters has to be
written inside double quotes like string constants. The RESTORE resets
the pointer of the current DATA position the program start so that next
READ will read from the first DATA found from the beginning of the

376
 15.125 DATA

program.
The instruction DATA stores numeric data in an optimized way: so, if
you enter a numeric constant that can be represented by a single byte,
it will be stored in the program as a single byte. Floating point numbers
are stored with default precision. Finally, strings are stored ”as is”. As
a result, when you use the READ command, ugBASIC will implicitly
perform the conversion if the same data type is not used, and if it is
posssible. It is possible to avoid this behavious by using the AS keyword,
followed by the data type.

Separates the definition of data from its use, makes the code more
readable and maintainable. You can change the data without having
to change the logic of the program. Finally, the same data can be read
multiple times in different parts of the program.
There is also a version of the syntax that allows you to load values from
an external file. This syntax is currently limited to numeric data that
must be separated by a non-numeric separator.
Abbreviated as Da
EXAMPLES
1 DATA 10 , 20 , " test "
2 DATA AS INTEGER 10 , 20 , 30
3 DATA LOAD " datas . txt " AS TEXT

377
 15 Keywords

15.126 DEC

SYNTAX
DEC variable

PURPOSE
The DEC command is used to decrement (i.e. decrease) the value of a
numeric variable by one. It is a quick and concise way to subtract 1
from the value contained in a variable. In place of variable, enter the
name of the numeric variable you want to decrement.
The DEC command is actually a shorthand for the subtraction operation,
as writing num=num-1. However, DEC is often preferred because of
its more concise syntax and its specific decrement function. The DEC
command can only be applied to numeric variables (integer).

See also INC

Abbreviated as Dc
EXAMPLES
1 x = 43
2 DEC x
3 PRINT x : ’ It prints "42"

378
 15.127 DECLARE FUNCTION

15.127 DECLARE FUNCTION

SYNTAX
DECLARE [SYSTEM] FUNCTION name AT address [ ( par1 [, par2
[, ... ] ] ) ] RETURN ret [ ON targets ]
par : name AS type ON register
par : name AS type ON STACK(width)
ret : register AS type | STACK(width) AS type
width: BYTE | WORD | DWORD
targets : name of targets, separated by comma (,)

PURPOSE
The DECLARE FUNCTION is a way to define and call external procedures
written in machine language and to insert assembly into the sources.
The procedures defined in this way can be called as if they were an
integral part of the language, and any result value can be retrieved by
calling it as a function:
value = test[]

See also DECLARE PROCEDURE

Abbreviated as DecFu
EXAMPLES
1 DECLARE SYSTEM FUNCTION test ON CPC , ZX

379
 15 Keywords

15.128 DECLARE PROC

SYNTAX
DECLARE [SYSTEM] PROC name AT address [ ( par [, par [, ...
] ] ) ] [ ON targets ]
par : name AS type ON register
par : name AS type ON STACK(width)
width: BYTE | WORD | DWORD
targets : name of targets, separated by comma (,)

PURPOSE
Alias for DECLARE PROCEDURE
See also DECLARE FUNCTION

Abbreviated as DecPrb
EXAMPLES
1 DECLARE SYSTEM PROC test ON CPC , ZX

380
 15.129 DECLARE PROCEDURE

15.129 DECLARE PROCEDURE

SYNTAX
DECLARE [SYSTEM] PROCEDURE name AT address [ ( par [, par
[, ... ] ] ) ] [ ON targets ]
par : name AS type ON register
par : name AS type ON STACK(width)
width: BYTE | WORD | DWORD
targets : name of targets, separated by comma (,)

PURPOSE
The DECLARE PROCEDURE is a way to define and call external procedures
written in machine language and to insert assembly into the sources.
The procedures defined in this way can be called as if they were an
integral part of the language. Once the procedure has been declared, it
will be sufficient to invoke it with one of the following syntaxes:
CALL test
PROC test
test[]

as if it were any ugBASIC procedure. If desired, parameters can be

added. For each it is obviously necessary to indicate how the value will
be passed to the function written in machine language.
The ugBASIC compiler allows you to declare functions and procedures
that are “system”. It means that the machine code resides in a ROM,
preloaded at run time and therefore already made available to any pro-
gram that knows how to call it.
However, since ugBASIC makes available all memory space allowed by
the hardware, it is possible that the ROMs have been disabled or oth-

381
 15 Keywords

erwise made unreachable. Indicating that you want to call a procedure

or a system function, ugBASIC will take care of re-enabling the ROM
before executing the request, deactivating it on exit.
To declare a procedure or function to be system, simply use the SYSTEM
keyword.
Alias for DECLARE PROC
See also DECLARE FUNCTION
Abbreviated as DecPrcd

EXAMPLES
1 DECLARE SYSTEM PROCEDURE test ON CPC , ZX

382
 15.130 DEFDGR

15.130 DEFDGR

SYNTAX
DEFDGR[$](x) = b0, b1, ... , b7

PURPOSE
This command allows you to customize a single character from those
used in graphical mode. The character is defined by means of an 8 pixel
by 8 pixel monochrome matrix.

If the system font has fewer pixels along one or both directions, the
character will be aligned to the top left and the extra pixels will be
ignored. The customization of the character occurs at runtime.
If you want to customize the characters used in text mode, or during
compilation, you must use the LOAD FONT command.
Abbreviated as Dfg
EXAMPLES
1 DEFDGR (0) = $ff , $ff , $ff , $ff , $00 , $00 , $00 , $00
2 DEFDGR$ (1) = $ff , $ff , $ff , $ff , $00 , $00 , $00 , $00

383
 15 Keywords

15.131 DEGREE

SYNTAX
DEGREE

PURPOSE
This command allows you to select the angle mode with trigonometric
functions, setting it to 360 degrees.

Abbreviated as Deg
EXAMPLES
1 x1 = COS (3.1415)
2 DEGREE
3 x2 = COS (180)
4 PRINT x1 ;" "; x2

384
 15.132 DELETE (constant)

15.132 DELETE (constant)

SYNTAX
= DELETE

PURPOSE
This constant represent the ”DELETE” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Del
EXAMPLES
1 IF KET STATE ( DELETE ) THEN
2 PRINT " DELETE has been pressed !"
3 ENDIF

385
 15 Keywords

15.133 DESTROY PORT

SYNTAX
DESTROY PORT portId

PURPOSE
The DESTROY PORT instruction destroy a message port that is not more
needed. The portId parameter is the same one that returned the call to
CREATE PORT function, and identifies the working port at that moment.

Alias for DOJO DESTROY PORT

Abbreviated as DesPrt
AVAILABLE ON

c64 c64reu coco coco3

EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = CREATE PORT ( sessionId , " testApp " )
3 DESTROY PORT port

386
 15.134 DIM (array)

15.134 DIM (array)

SYNTAX
DIM name [AS type] (d1[,d2[,...]]) [ro] [fl]
DIM name [AS type] (d1[,d2[,...]]) = #"["hex"]" [ro] [fl]
DIM name [AS type] (d1[,d2[,...]]) = #v,v,... [ro] [fl]
DIM name [AS type] WITH v (d1[,d2[,...]]) [ro] [fl]
ro: [READ ONLY|READONLY]
fl: [BANKED|BANKED(n)|UNBANKED|FOR BANK READ|FOR BANK WRITE]

PURPOSE
The DIM command is used to reserve a specific space in the computer’s
memory to hold data that you will use during the execution of your
program. In practice, it is like reserving empty boxes where you can
store objects (data) of different sizes and types.

The DIM command is used primarily to create arrays, which are data
structures that allow you to group multiple values under a single name,
accessing each value through a numeric index. You can define both
vectors (mono dimensional array) or a multidimensional array of values,
and to initialize this array with the preferred values. You must also
specify the size of the array, that is, the number of elements it can
contain. When you declare an array with DIM, you reserve a portion of
memory sufficient to hold all the elements of the array.
The simplest syntax is that which defines a vector of a single dimen-
sion: in this case, it is sufficient to indicate the number of elements in
parentheses. With the keyword AS you can indicate the data type of
each single element.
You can, of course, define a matrix (i.e. a vector with two or more
dimensions). In this case it is sufficient to indicate the number of
elements for each dimension, separating them with a comma.

387
 15 Keywords

By definition, the array will be initialized with a value of zero for each
element. You can change this behavior by specifying an initialization
by assignment. The initialization can be done by indicating a single
initialization value, each single value of each single element, with the
same type of data with which the matrix was created (with the # ...
syntax), or by describing the memory area that will occupy the array,
byte by byte (with the # [...] syntax ).
The array could be assigned to a ”read only” memory, in order to save
RAM space. This can be done using READ ONLY flag.

Finally, the array can be assigned to a specific expansion bank by using

the BANKED keyword. Otherwise, if an array could be used as destination
of BANK READ / BANK WRITE command, you should add this flag.
Arrays allow you to organize data in a structured way, making it easier
to access and manipulate. By declaring arrays before using them, you
define a specific size of the data. The DIM command makes code more
readable, because it explicitly declares the data structures used.
See also DIM (variable)
Abbreviated as Di

EXAMPLES
1 DIM x (42)
2 DIM values AS DWORD (20 ,20) BANKED
3 DIM y AS BYTE (8) = #[ f f 8 0 f f 8 0 f f 8 0 f f 8 0 ]
4 DIM z AS BYTE (8) = _
5 #{ 255 , 128 , 255 , 128 , 255 , 128 , 255 , 128 }
6 DIM scores WITH 0 (2)
7 DIM x (42)
8 DIM y (4) AS BYTE = #{ 1 , 2 , 3 , 4 }

388
 15.135 DIM (variable)

15.135 DIM (variable)

SYNTAX
DIM name [AS type] [= v][,name [AS type] [= v][, ...]]

PURPOSE
The DIM command is used to reserve a specific space in the computer’s
memory to hold data that you will use during the execution of your
program. In particular, you can use DIM for a single variable

Declaring variables explicitly makes your code more readable and un-
derstandable, especially in longer programs. Specifying the data type
prevents type errors when your program runs. You can initialize a vari-
able when you declare it, giving it an initial value different by 0 (the
ugBASIC default value). Moreover, when you need to use a particu-
lar data type (e.g. FLOAT for scientific calculations), it is advisable to
explicitly declare the variable.
The scope of a variable declared with DIM depend on the context in
which it is declared. It may be local to a procedure or global to the en-
tire program. It is always a good practice to declare all variables at the
beginning of a program or procedure to improve readability and main-
tainability of the code, and ugBASIC gives you the OPTION EXPLICIT
directive to ensure that you use only defined variables.
Note that ugBASIC language, as other BASIC dialect, do not need to
use DIM to declare a variable. The data type and scope is inferred from
the context in which the variable is first used.

Alias for VAR

See also DIM (array)
Abbreviated as Di

389
 15 Keywords

EXAMPLES
1 DIM x AS INTEGER = 42 , y AS BYTE = 21

390
 15.136 DISABLE INTERRUPT

15.136 DISABLE INTERRUPT

SYNTAX
DISABLE INTERRUPT

PURPOSE
An interrupt is a signal that temporarily stops the normal execution of
a program, allowing the processor to handle external events or internal
exceptions. These events can be a key being pressed on the keyboard,
data arriving from a serial port or a timer reaching zero.
Interrupts allow the processor to respond quickly and efficiently to ex-
ternal events, avoiding delays in processing, so that you can handle
events that occur independently of the main program execution and so
the computer can communicate with external devices such as keyboard.

This instruction will change the specific register of the main processor,
so that interrupts will not be served anymore.
See also ENABLE INTERRUPT
Abbreviated as DxIntr

EXAMPLES
1 DISABLE INTERRUPT

391
 15 Keywords

15.137 DISTANCE

SYNTAX
= DISTANCE( [x1], [y1] TO [x2], [y2] )

PURPOSE
The DISTANCE function calculates the geometric distance between two
points. The distance is calculated with the application of the Pythagorean
theorem, the result of which is however returned with the nnly integer
part. If any component is omitted, the last screen position is used,
instead.
Abbreviated as Dst
EXAMPLES
1 result = DISTANCE ( x1 , y1 TO x2 , y2 )

392
 15.138 DIV

15.138 DIV

SYNTAX
DIV var, divisor[, remainder]

PURPOSE
The DIV statement allows you to make a division using the dividend
as a variable where the result will be stored. Optionally, it is possi-
ble to indicate a variable where to store the remainder of the division
operation.
Abbreviated as Dv
EXAMPLES
1 DIV a ,2
2 DIV a ,3 , q

393
15 Keywords

15.139 DLOAD

SYNTAX
DLOAD filename [FROM offset] [TO address] [SIZE size]

PURPOSE
The DLOAD command load data from a mass storage (normally, a floppy
disk) into the computer’s memory. This data can be programs, numeric
data, text, or any other information that has previously been saved to
disk.
The DLOAD command was primarily used to load numeric data, text, or
images for use within a program. Some games allowed you to save the
current state of the game to a disk using DLOAD so you could resume
playing at a later time.

The syntax allows you to load a specific file (filename) starting from a
specific offset within the file, towards a specific address in memory
for a certain number of bytes. Note that the behavior of this instruc-
tion strictly depends on the target where it is executed. It follows that
not all options are necessarily available on every target.

The time it takes to load a file depended on the speed of the drive and
the size of the file. Files loaded had to be in the correct format for the
computer and the program using them. The amount of data that could
be loaded was limited by the available RAM.
On the atari and atarixl target, it is not possible to omit the number
of bytes and the starting address.
On the c64 and c128 target, you cannot indicate the offset and the
size.
See also DLOAD ERROR

394
 15.139 DLOAD

Abbreviated as Dl
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3 cpc vic20

EXAMPLES
1 DLOAD " test " TO finalAddress SIZE 16

395
15 Keywords

15.140 DLOAD ERROR

SYNTAX
= DLOAD ERROR

PURPOSE
The DLOAD ERROR function lets you know whether the last DLOAD in-
struction returned an error or not.

See also DLOAD

Abbreviated as DlEr
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3 cpc vic20

396
 15.141 DO NULL

15.141 DO NULL

SYNTAX
DO NULL

PURPOSE
Wait for a keystroke. If a program comes to a DO NULL instruction,
it waits until the user presses a key. Differently from TSB, further
commands can follow on the same BASIC line in the progra, and it can
be used in an IF line (after THEN or ELSE).
See also WAIT KEY
Abbreviated as DoNULL

EXAMPLES
1 DO NULL

397
 15 Keywords

15.142 DO...LOOP

SYNTAX
DO
... instructions ...
LOOP

PURPOSE

The DO...LOOP command is used for repeatedly executing a block of

statements. It creates a loop, which is a sequence of statements that is
executed repeatedly, forever (unless exits using the EXIT keyword). You
can nest DO LOOPs within other loops, creating more complex control
structures.
If you want to repeat the statements a set number of times, the FOR...NEXT
statement is usually a better choice, while if you want to repeat for spe-
cific conditions, you should use the WHILE...WEND and REPEAT...UNTIL
statements.
It can be used, i.e., to ask the user to enter a choice and repeat the
menu until the exit option is selected. If you want to exit a loop, make
sure the exit condition of the loop is changed within the loop itself,
otherwise you may create an infinite loop. If possible, avoid performing
complex calculations within the exit condition, as they will be repeated
with each iteration of the loop.
See also FOR...NEXT, WHILE...WEND, REPEAT...UNTIL

Abbreviated as DoLp
EXAMPLES
1 DO
2 x = x + 1
3 LOOP

398
 15.143 DOJO CREATE PORT

15.143 DOJO CREATE PORT

SYNTAX
= DOJO CREATE PORT( sessionId, application )

PURPOSE
Alias for CREATE PORT
Abbreviated as DjCrtPrt

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )
2 port = DOJO CREATE PORT ( sessionId , " testApp " )

399
 15 Keywords

15.144 DOJO DESTROY PORT

SYNTAX
DESTROY PORT portId

PURPOSE
Alias for DOJO DESTROY PORT
Abbreviated as DjDesPrt

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )
2 port = DOJO CREATE PORT ( sessionId , " testApp " )
3 DOJO DESTROY PORT port

400
 15.145 DOJO FIND PORT

15.145 DOJO FIND PORT

SYNTAX
port = DOJO FIND PORT( sessionId, username, application )

PURPOSE
Alias for DOJO FIND PORT
Abbreviated as DjFndPrt

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )
2 port = DOJO FIND ( sessionId , " user2 " , " testApp " )

401
 15 Keywords

15.146 DOJO GET MESSAGE

SYNTAX
port = GET MESSAGE( portId )

PURPOSE
Alias for GET MESSAGE
Abbreviated as DjGeMsg

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = FIND ( sessionId , " user2 " , " testApp " )
3 msg = GET MESSAGE ( port )

402
 15.147 DOJO LOGIN

15.147 DOJO LOGIN

SYNTAX
= DOJO CREATE PORT( sessionId, application )

PURPOSE
Alias for LOGIN
Abbreviated as DjLgn

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )

403
 15 Keywords

15.148 DOJO PEEK MESSAGE

SYNTAX
= DOJO PEEK MESSAGE( portId )

PURPOSE
Alias for PEEK MESSAGE
Abbreviated as DjPkMsg

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )
2 port = DOJO FIND ( sessionId , " user2 " , " testApp " )
3 IF DOJO PEEK MESSAGE ( port ) THEN
4 PRINT " A message is arrived !"
5 ENDIF

404
 15.149 DOJO PING

15.149 DOJO PING

SYNTAX
= DOJO PING()

PURPOSE
Alias for PING
Abbreviated as DjPin

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 IF DOJO PING ( ) THEN
2 PRINT " DOJO is available "
3 ENDIF

405
 15 Keywords

15.150 DOJO PUT MESSAGE

SYNTAX
DOJO PUT MESSAGE portId, string

PURPOSE
Alias for PUT MESSAGE
Abbreviated as DjPuMsg

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = DOJO LOGIN ( " user " , " password " )
2 port = DOJO FIND ( sessionId , " user2 " , " testApp " )
3 DOJO PUT MESSAGE port , " hello !"

406
 15.151 DOJO READY

15.151 DOJO READY

SYNTAX
= DOJO READY()

PURPOSE
Alias for READY
Abbreviated as DjR#y

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 IF DOJO READY ( ) THEN
2 PRINT " DOJO data is available "
3 ENDIF

407
 15 Keywords

15.152 DOJO RECEIVE

SYNTAX
= DOJO RECEIVE()

PURPOSE
Alias for RECEIVE
Abbreviated as DjRcv

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 IF DOJO READY ( ) THEN
2 PRINT DOJO RECEIVE ()
3 ENDIF

408
 15.153 DOJO SEND

15.153 DOJO SEND

SYNTAX
DOJO SEND data

PURPOSE
Alias for SEND
Abbreviated as DjSen

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 IF DOJO READY ( ) THEN
2 PRINT DOJO RECEIVE ()
3 ENDIF

409
 15 Keywords

15.154 DOJO SUCCESS

SYNTAX
= DOJO SUCCESS( )

PURPOSE
Alias for SUCCESS
Abbreviated as DjSu

AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 success = DOJO SUCCESS ( )

410
 15.155 DOJOKA (data type)

15.155 DOJOKA (data type)

SYNTAX
... AS DOJOKA

PURPOSE
This data type holds a reference to a connection or communication port
with the DOJO protocol.

Abbreviated as Djk
EXAMPLES
1 DIM accessId AS DOJOKA
2 accessId = LOGIN ( " user " , " password " )

411
15 Keywords

15.156 DOUBLE BUFFER

SYNTAX
DOUBLE BUFFER [ON|OFF]

PURPOSE
The DOUBLE BUFFER is a command that enable / disable the graphics
programming technique used to avoid screen flickering, which is es-
pecially noticeable in animations and interactive graphics applications.
It is especially useful in 8-bit computers, where graphics resources are
limited.
Imagine having a screen and two areas of memory, called buffers, dedi-
cated to graphics. In the first the entire frame (the complete image) that
we want to display on the screen is drawn. While drawing in the first
buffer, the contents of the second buffer are displayed on the screen.
Once the drawing in the first buffer is complete, the two buffers are
swapped: the contents of the first buffer are copied to the second and
displayed on the screen, while the first buffer is emptied and prepared
for the next frame. This process is repeated continuously.
The command will enable this method, and screens will be swapped if
the SCREEN SWAP is used.
This instruction activates the technique only where available.
See also SCREEN SWAP

Abbreviated as DbBf
AVAILABLE ON
c128 c64 c64reu coco3 pc128op to8
EXAMPLES

412
 15.156 DOUBLE BUFFER

1 DOUBLE BUFFER ON

413
 15 Keywords

15.157 DOWN (constant)

SYNTAX
= DOWN

PURPOSE
This constant represent the ”DOWN” key (move cursor down), when
used as a value to compare with SCANCODE,KEY STATE and KEY PRESSED.
If the key does not exist in the corresponding target, the value will be
zero.
This constant represent the ”DOWN” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Dw
EXAMPLES
1 IF KET STATE ( DOWN ) THEN
2 PRINT " DOWN has been pressed !"
3 ENDIF

414
 15.158 DRAW (instruction)

15.158 DRAW (instruction)

SYNTAX
DRAW (x1,y1)-(x2,y2),c[,B[F]]
DRAW (x1,y1)-(x2,y2),c[,[mode]][,B[F]]
DRAW [x1], [y1] TO x2, y2[, c]
DRAW TO [y2],[y2][,c]

PURPOSE

The DRAW command allows you to draw line segments and rectangles
on the screen, forming one of the basic building blocks for creating
simple graphics. This command can be used to draw coordinate axes
and data points, to create characters, environments, and objects, to
draw windows, buttons, and other interface elements.

It starts drawing from the coordinates (x1, y1) to arrive at the coor-
dinates (x2, y2), using the color c. The start or the final coordinates
can be omitted: in this case, ugBASIC will draw, respectively, starting
from the last drawn position and arriving at the last drawn position.
If the color is omitted, the last color selected with the INK or PEN
command will be used.

The DRAW command offers several additional options to customize the

drawing. After the color, that is optinal, you can put the letter B to
draw a rectangle. The letters BF means that the rectangle must be
filled, too. Finally, the default line style is normally ”complete” but a
16 bit bitmask can be set with the SET LINE command. You can also
select the mode that can be PSET or PRESET. If PSET is used the line is
drawn in the current foreground colour. If PRESET, the line is drawn in
the background colour.
The accuracy of the drawings is limited by the resolution of the screen,
and drawing many lines can slow down the program, especially on 8-bit

415
15 Keywords

computers.
Alias for LINE
See also BAR, BOX, SET LINE

Abbreviated as Dr

416
 15.159 DRAW (program)

15.159 DRAW (program)

SYNTAX
DRAW instructions

PURPOSE
The DRAW command allows to draw on the SCREEN. The parameter
is either a string constant, or a string variable, containing a set of the
draw subcommands. Usually the first action of any drawing is to move
to the start point.
M x,y means move to the coordinates given by x,y. If you wanto to
move to a point, it is usually a good idea to make a ”blank” move, that
is move without drawing or lifting the pencil off the paper.
If you do not you may get unwanted lines on your drawing, you can
use the letter B. Any drawing instruction following the B will be a blank
line. BMx,y means move to the x,y without drawing. Having decided
the start point, you may now move up (U), down (D), right (R), or Left
(L) by as many pixels as you like. The sequence U20R20D20L20 will
cause drawing a square.

Apart from vertical and horizontal lines you can also draw diagonal lines.
These use the subcommands E,F,G and H, for instance E12 will draw
a diagonal line, 12 points long, at 45 degrees from the vertical. All
the angles are measured from the vertical as follows: E = 45 degrees,
F = 135 degrees, G = 225 degrees and H = 315 degrees. This allows
diagonal lines to be drawn in any of 4 directions.

We can change the color by using C. The letter C is followed by a number

from 0 to COLOR COUNT, representing the code for one of the available
colours.
If the drawing is a bit small, we can scale it up with the S parameter.

417
 15 Keywords

The S means scale, and allows a drawing, or parts of a drawing to be

scaled up or down in units of 1/4 (0.25). So S1 reduces the drawing to
1/4 scale, S2 to 2/4 (half) scale, S8 to 8/4 (twice) scale, and so on.
The default setting for scale is 4/4 (i.e. 1, the original size).

Another option available is the angle parameter A. This allows us to

rotate all or part of the drawing, as all lines after the A will be drawn
with the displacement given by An, where n is a number between 0 and
3, as follows, 0 = 0 degrees, 1 = 90 degrees, 2 = 180 degrees, 3 = 270
degrees.

Finally, the N command has the meaning of no update of drawing po-

sition. This is to draw a line as specified but do not use the end of the
line as the new position.
Abbreviated as Dr

EXAMPLES
1 DRAW " BM0 ,0; R10 ; U10 ; L10 ; D10 "

418
 15.160 DSAVE

15.160 DSAVE

SYNTAX
DSAVE filename [TO offset] [FROM address] [SIZE size]

PURPOSE
Dynamically (at run-time) save a file to a mass storage. The DSAVE
command allows you to (dynamically) save a file to a mass device. The
syntax allows you to save a specific file (filename) starting from a
specific offset within the file, from a specific address in memory for
a certain number of bytes. Note that the behavior of this instruction
strictly depends on the target where it is executed. It follows that not
all options are necessarily available on every target.
See also DSAVE ERROR

Abbreviated as Dsa
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3

EXAMPLES
1 DSAVE " test " FROM finalAddress SIZE 16

419
15 Keywords

15.161 DSAVE ERROR

SYNTAX
= DSAVE ERROR

PURPOSE
The DSAVE ERROR function lets you know whether the last DSAVE in-
struction returned an error or not.

See also DSAVE

Abbreviated as DsaEr
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3

420
 15.162 DTILE

15.162 DTILE

SYNTAX
DTILE v ROW y, x1 TO x2[, c]
DTILE v COLUMN x, y1 TO y2[, c]

PURPOSE
This command allows you to draw a row or column of ”tiles”, or pre-
defined characters.

Alias for DTILES

Abbreviated as Dt

421
15 Keywords

15.163 DTILES

SYNTAX
DTILES v ROW y, x1 TO x2[, c]
DTILES v COLUMN x, y1 TO y2[, c]

PURPOSE
Alias for DTILE

Abbreviated as Dts

422
 15.164 DUP

15.164 DUP

SYNTAX
= DUP( string, times )

PURPOSE
The DUP command allows you to duplicate portions of text within a
program. This feature is especially useful when you need to repeat
a sequence of characters multiple times, without having to retype it
manually.
The DUP command can be combined with other commands to create
more complex effects. You can concatenate the result of DUP with
other strings to form sentences or paragraphs. You can assign the
result of DUP to a variable for later use. You can combine it with other
string manipulation functions to create even more customized effects.
Displaying an increasing number of characters in a bar can use DUP, as
well as to write tables or reports with fixed-width columns.
Abbreviated as Du

EXAMPLES
1 PRINT DUP ( "***" , 10 )

423
 15 Keywords

15.165 DWORD (data type)

SYNTAX
... AS DWORD

PURPOSE
The DWORD is a data type that allow to store a 32-bit word (WORD).
Abbreviated as 32BIT

EXAMPLES
1 DIM parolaLunga AS DWORD

424
 15.166 ELLIPSE

15.166 ELLIPSE

SYNTAX
ELLIPSE [x],[y],[rx],[ry][, c]

PURPOSE
This command allows you to draw an ellipse with starting coordinates
in (x,y) and radius rx for the horizontal component and ry for the
vertical component. The color is indicated by the parameter c. If the
abscissa and/or ordinate is omitted, the last graphic position drawn will
be used. In addition, the color can also be omitted and, if necessary,
the last color set with the PEN or INK command will be used.
See also CIRCLE

Abbreviated as Ell
EXAMPLES
1 ELLIPSE 100 ,100 ,42 ,21
2 ELLIPSE , ,10 ,20 , RED

425
 15 Keywords

15.167 EMPTY TILE

SYNTAX
= EMPTY TILE
EMPTY TILE = ...

PURPOSE
This is a special parameter of ugBASIC, which allows you to change
what is considered the ”space” character on the screen. It is used, in
text modes, to clear the screen.
Alias for EMPTYTILE
Abbreviated as EmTl

EXAMPLES
1 EMPTY TILE = 65
2 CLS

426
 15.168 EMPTYTILE

15.168 EMPTYTILE

SYNTAX
= EMPTYTILE
EMPTYTILE = ...

PURPOSE
Alias for EMPTY TILE

Abbreviated as Emt
EXAMPLES
1 EMPTYTILE = 65
2 CLS

427
 15 Keywords

15.169 ENABLE INTERRUPT

SYNTAX
ENABLE INTERRUPT

PURPOSE
An interrupt is a signal that temporarily stops the normal execution of
a program, allowing the processor to handle external events or internal
exceptions. These events can be a key being pressed on the keyboard,
data arriving from a serial port or a timer reaching zero.
Interrupts allow the processor to respond quickly and efficiently to ex-
ternal events, avoiding delays in processing, so that you can handle
events that occur independently of the main program execution and so
the computer can communicate with external devices such as keyboard.

This instruction will change the specific register of the main processor,
so that interrupts will be served again.
See also DISABLE INTERRUPT
Abbreviated as EnIntr

EXAMPLES
1 ENABLE INTERRUPT

428
 15.170 END

15.170 END

SYNTAX
END

PURPOSE
The END command is used to terminate the execution of a program.
When the computer encounters this command, it stops executing sub-
sequent instructions.

Generally, the END command is placed at the end of a program to in-

dicate its conclusion. It can be used within the program to interrupt
execution in a controlled manner, for example when a particular condi-
tion occurs.

When the END command is encountered, the computer stops immedi-

ately execution, also interrupts are not served anymore. This is different
from the HALT command, which only suspends execution but not inter-
rupts.
See also HALT

Abbreviated as Ee
EXAMPLES
1 END

429
 15 Keywords

15.171 END GAMELOOP

SYNTAX
END GAMELOOP

PURPOSE
Define the ending point of a game loop.
Abbreviated as EeGl

AVAILABLE ON
c128 c128z c64 coleco cpc pc128op to8 vg5000
EXAMPLES
1 END GAMELOOP

430
 15.172 ENDSELECT

15.172 ENDSELECT

SYNTAX
CASE expression

PURPOSE
The ENDSELECT command is part of SELECT...ENDSELECT construct,
and delimit the end of the SELECT CASE.

See also SELECT CASE, CASE ELSE, ENDSELECT

Abbreviated as Es
EXAMPLES
1 SELECT CASE answer
2 CASE 42
3 PRINT " The answer !"
4 CASE ELSE
5 PRINT " I am still thinking ..."
6 ENDSELECT

431
 15 Keywords

15.173 ENVELOPE

SYNTAX
ENVELOPE voice, attack, decay, release

PURPOSE
The ENVELOPE command is used to define the volume of a sound over
time, or its envelope. In simpler terms, it allows you to create richer
and more complex sound effects, by defining the initial phase in which
the sound rapidly increases in volume, the phase in which the sound
decreases in volume, the final phase in which the sound fades away until
it disappears. The ENVELOPE command uses internal tone generators
to create these effects.
This command simulates different musical instruments, such as pianos,
drums, sound effects, and more. It creates more complex and dynamic
melodies and harmonies, and it can be used to create sound effects for
games, such as explosions, gunshots, or ambient sounds.
Abbreviated as Env

EXAMPLES
1 ENVELOPE 1 , 1 , 8 , 10

432
 15.174 EQUAL (constant)

15.174 EQUAL (constant)

SYNTAX
= EQUAL

PURPOSE
This constant represent the ”EQUAL” key (=), when used as a value
to compare with SCANCODE,KEY STATE and KEY PRESSED. If the key
does not exist in the corresponding target, the value will be zero.

Abbreviated as Eq
EXAMPLES
1 IF KET STATE ( EQUAL ) THEN
2 PRINT " EQUAL has been pressed !"
3 ENDIF

433
 15 Keywords

15.175 EVERY OFF

SYNTAX
EVERY OFF [timer]

PURPOSE
With EVERY OFF you can enable (or re-enable) the timed calls.
See also AFTER...GOSUB, AFTER...CALL, EVERY ON

Abbreviated as EvOf
AVAILABLE ON
atari atarixl c128 c64 coco coco3 coleco d32 d64 pc128op
plus4 to8 vic20

EXAMPLES
1 EVERY OFF

434
 15.176 EVERY ON

15.176 EVERY ON

SYNTAX
EVERY ON [timer]

PURPOSE
With EVERY ON you can enable (or re-enable) the timed calls.
See also AFTER...GOSUB, AFTER...CALL, EVERY OFF

Abbreviated as EvON
AVAILABLE ON
atari atarixl c128 c64 c64reu coco coco3 coleco d32 d64 mo5
pc128op plus4 to8 vic20

EXAMPLES
1 EVERY ON

435
15 Keywords

15.177 EVERY...CALL

SYNTAX
EVERY value[,timer] TICKS CALL identifier

PURPOSE
The EVERY allows to execute a procedure at specified intervals of time.
It is especially useful for creating animations, handling real-time events,
and simulating dynamic behavior in your programs. You can give the
value as number of ticks to wait for triggering the call, and timer to
select a specific timer (up to 8 timers are present).
It allows you to create smooth animations by moving objects on the
screen at regular intervals, and it is essential for managing real-time
events, such as character movement, object collisions, and keyboard
input management. It can be used also to simulate physical or biological
phenomena that evolve over time., or to create dynamic visual effects,
such as sparks, explosions, or screen transitions.
The speed at which EVERY commands execute depends on the frame
rate of your computer, and from the parameter value given. A higher
frame rate means that actions will be executed more frequently, while
an higher value means that actions will be executed less frequently.
Note that the procedure execution time should be less than the interval
time, or the main program timings will be affected!
There are 8 delay timers from 0 to 7 which can be specified with timer.
If omitted timer defaults to 0. In the case of parallel task has 0 the
highest and 8 the lowest priority.
With EVERY OFF and EVERY ON you can disable or enable the timed
calls. Procedures run as long as the main loop / program runs, even
the main programm is paused. It is important to know or realise that

436
 15.177 EVERY...CALL

low-priority-procedures which occurs simultanously to higher-priority-

procedures are not lost. Their task remains or handled again after
finishing the higher-prio interrupt.
Important: the meaning of this command is not altered by OPTION
CALL pragma, so this is always a GOSUB and not a GOTO!
See also AFTER...GOSUB, EVERY ON, EVERY OFF
Abbreviated as EvCa
AVAILABLE ON

atari c128 c64 coco coco3 coleco d32 d64 mo5 msx1 pc128op
plus4 sc3000 sg1000 to8 vg5000 vic20
EXAMPLES
1 EVERY 50 TICKS CALL c h a n g e B o r d e r C o l o r
2 EVERY 50 ,2 TICKS CALL c h a n g e B o r d e r C o l o r

437
15 Keywords

15.178 EVERY...GOSUB

SYNTAX
EVERY value TICKS GOSUB identifier
EVERY value[,timer] TICKS CALL identifier

PURPOSE
Define the call of a sub-routine at regular intervals, without interfering
with the main program. You must specifying the length of time between
every call, measured in TICKS.
Note that the subroutine execution time should be less than the interval
time, or the main program timings will be affected. After a subroutine
has been entered, the EVERY system is automatically disabled. This
means that, in order to call this feature continuously, an EVERY ON
command must be inserted into a subroutine before the final RETURN
statement.
The EVERY allows to call a subroutine at specified intervals of time. It
is especially useful for creating animations, handling real-time events,
and simulating dynamic behavior in your programs. You can give the
value as number of ticks to wait for triggering the call, and timer to
select a specific timer (up to 8 timers are present).
It allows you to create smooth animations by moving objects on the
screen at regular intervals, and it is essential for managing real-time
events, such as character movement, object collisions, and keyboard
input management. It can be used also to simulate physical or biological
phenomena that evolve over time., or to create dynamic visual effects,
such as sparks, explosions, or screen transitions.
The speed at which EVERY commands execute depends on the frame
rate of your computer, and from the parameter value given. A higher

438
 15.178 EVERY...GOSUB

frame rate means that actions will be executed more frequently, while
an higher value means that actions will be executed less frequently.
Note that the procedure execution time should be less than the interval
time, or the main program timings will be affected!

There are 8 delay timers from 0 to 7 which can be specified with timer.
If omitted timer defaults to 0. In the case of parallel task has 0 the
highest and 8 the lowest priority.
With EVERY OFF and EVERY ON you can disable or enable the timed
calls. Procedures run as long as the main loop / program runs, even
the main programm is paused. It is important to know or realise that
low-priority-procedures which occurs simultanously to higher-priority-
procedures are not lost. Their task remains or handled again after
finishing the higher-prio interrupt.

Important: the meaning of this command is not altered by OPTION

CALL pragma, so this is always a GOSUB and not a GOTO!
See also AFTER...CALL, EVERY ON, EVERY OFF
Abbreviated as EvGs

AVAILABLE ON
atari c128 c64 coco coco3 coleco d32 d64 mo5 pc128op plus4
to8 vic20
EXAMPLES
1 EVERY 50 TICKS GOSUB c h a n g e B o r d e r C o l o r
2 EVERY 50 TICKS CALL c h a n g e B o r d e r C o l o r
3 EVERY 50 ,2 TICKS CALL c h a n g e B o r d e r C o l o r

439
 15 Keywords

15.179 EXEC

SYNTAX
EXEC address
[ WITH REG(r1)=v1[, REG(r2)=v2 [, ... ] ] ]
[ RETURN x1=REG(r1)[, x2=REG(r2)[, ... ] ] ]
[ ON target1[, target2[, ... ] ] ]

PURPOSE

This command allows you to start the execution of a subroutine, written

directly in machine language, starting from the indicated address. It
must be noted that this jump is intended as a return: any assembly
instruction that returns from execution will continue the execution of
the program from the next ugBASIC line.

Moreover, it is possible to communicate with the machine code. This is

made possible by indicating, at the same time as the call, the population
of specific input registers and the recovery of values from specific output
registers.
The extended syntax allow the specification of r1, r2, .. as the various
processor registers, v1, v2, .. are the values passed in the various
registers and x1, x2, .. are the variables that will receive the execution
result from the various registers. Since the registers are different from
CPU to CPU, it can be useful to add the ON target specification.
See also SYS

Abbreviated as E#
EXAMPLES
1 EXEC #49142
2 EXEC indirizzo
3 EXEC indirizzo WITH REG ( A ) =42 RETURN y = REG ( B ) ON CPUZ80

440
 15.180 EXIT

15.180 EXIT

SYNTAX
EXIT [number]

PURPOSE
The EXIT command is used to stop execution of a specific block of code
and transfer control of the program to the first statement following
that block. It is often used inside FOR...NEXT, WHILE...WEND, or
DO...LOOP loops to terminate the loop prematurely when a certain
condition is met. The optional parameter number specifies the number
of inner blocks you want to exit. If missing, the implicit value is 1.
The command is useful to exit when an error or unexpected condition
occurs, and it can be used to end the code block and handle the error
appropriately. In some cases, using EXIT can make your code more
efficient by avoiding executing unnecessary statements. EXIT allows
you to create more complex control flows and make dynamic decisions
during program execution. Excessive use of EXIT, however, can make
your code more difficult to read and maintain.

Abbreviated as Ex
EXAMPLES
1 EXIT
2 EXIT 2

441
 15 Keywords

15.181 EXIT IF

SYNTAX
EXIT IF expression[, number]
EXIT number IF expression

PURPOSE
The instruction forces the program to leave a loop, such as FOR...NEXT,
REPEAT...UNTIL, WHILE...WEND and DO...LOOP under a specific set
of conditions. The EXIT will only be performed IF the result is found
to true.
An optional number can be given to specify the number of loops to be
jumped out, otherwise only the current loop will be aborted.

Abbreviated as ExIf
EXAMPLES
1 EXIT IF lifes = 0 , 2
2 EXIT 2 IF lifes

442
 15.182 EXIT PROC

15.182 EXIT PROC

SYNTAX
EXIT PROC

PURPOSE
Alias for POP PROCEDURE, EXIT PROCEDURE
Abbreviated as ExPrb

EXAMPLES
1 EXIT PROC

443
 15 Keywords

15.183 EXIT PROC IF

SYNTAX
EXIT PROC IF expression

PURPOSE
Alias for EXIT PROCEDURE IF
Abbreviated as ExPrbIf

EXAMPLES
1 EXIT PROC IF

444
 15.184 EXIT PROC WITH...IF

15.184 EXIT PROC WITH...IF

SYNTAX
EXIT PROC WITH value IF expression

PURPOSE
Alias for EXIT PROCEDURE WITH...IF
Abbreviated as ExPrbWiIf

EXAMPLES
1 PROCEDURE test [ x AS INTEGER ]
2 EXIT PROC WITH 0 IF x > 10
3 PRINT " X is less or equal to 10"
4 RETURN 1
5 END PROC

445
 15 Keywords

15.185 EXIT PROCEDURE

SYNTAX
EXIT PROCEDURE

PURPOSE
The EXIT PROCEDURE command is used to stop execution of a specific
procedure, and transfer control of the program to the first statement
following the calling of that procedure.

The command is useful to exit when an error or unexpected condition

occurs, and it can be used to end the procedure and handle the error
appropriately. In some cases, using EXIT PROCEDURE can make your
code more efficient by avoiding executing unnecessary statements. EXIT
PROCEDURE allows you to create more complex control flows and make
dynamic decisions during program execution. Excessive use of EXIT
PROCEDURE, however, can make your code more difficult to read and
maintain.
Alias for POP PROCEDURE, EXIT PROC

Abbreviated as ExPrcd
EXAMPLES
1 PROCEDURE test [ x AS INTEGER ]
2 IF x > 10 THEN EXIT PROCEDURE
3 PRINT " X is less or equal to 10"
4 ENDIF
5 END PROC

446
 15.186 EXIT PROCEDURE IF

15.186 EXIT PROCEDURE IF

SYNTAX
EXIT PROCEDURE IF expression

PURPOSE
The EXIT PROCEDURE IF command is used to stop execution of a spe-
cific procedure, and transfer control of the program to the first state-
ment following the calling of that procedure, in case an expression is
true.TRUE
The command is useful to exit when an error or unexpected condition
occurs, and it can be used to end the procedure and handle the error
appropriately. In some cases, using EXIT PROCEDURE IF can make
your code more efficient by avoiding executing unnecessary statements.
EXIT PROCEDURE IF allows you to create more complex control flows
and make dynamic decisions during program execution. Excessive use
of EXIT PROCEDURE IF, however, can make your code more difficult
to read and maintain.
Alias for EXIT PROC IF

Abbreviated as ExPrcdIf
EXAMPLES
1 PROCEDURE test [ x AS INTEGER ]
2 EXIT PROCEDURE IF x > 10
3 PRINT " X is less or equal to 10"
4 END PROC

447
 15 Keywords

15.187 EXIT PROCEDURE WITH...IF

SYNTAX
EXIT PROCEDURE WITH value IF expression

PURPOSE
The EXIT PROCEDURE WITH...IF command is used to stop execution
of a specific function, and transfer control of the program to the first
statement following the calling of that procedure, giving back a value
in case an expression is true.TRUE
The command is useful to exit when an error or unexpected condition
occurs, and it can be used to end the procedure and handle the er-
ror appropriately. In some cases, using EXIT PROCEDURE WITH...IF
can make your code more efficient by avoiding executing unnecessary
statements. EXIT PROCEDURE WITH...IF allows you to create more
complex control flows and make dynamic decisions during program ex-
ecution. Excessive use of EXIT PROCEDURE WITH...IF, however, can
make your code more difficult to read and maintain.
Alias for EXIT PROC IF

Abbreviated as ExPrcdWiIf
EXAMPLES
1 PROCEDURE test [ x AS INTEGER ]
2 EXIT PROCEDURE WITH 0 IF x > 10
3 PRINT " X is less or equal to 10"
4 RETURN 1
5 END PROC

448
 15.188 EXP

15.188 EXP

SYNTAX
= EXP(number)

PURPOSE
The EXP command is a mathematical function that calculates the nat-
ural exponential of a number. In other words, it raises Napier’s number
(e = 2.71828) to the specified power.

The EXP function has numerous applications in mathematics, science,

and engineering. It is used to describe phenomena that grow at a
rate proportional to the amount present, such as population growth or
radioactive decay. The natural exponential is closely related to trigono-
metric functions and can be used to calculate them.

Many differential equations have solutions that involve the natural ex-
ponential, and it appears in many probability distributions, such as the
exponential distribution and the normal distribution.
Noe that EXP function is defined only for FLOAT numbers.

EXAMPLES
1 x = EXP (21)

449
 15 Keywords

15.189 FALSE (constant)

SYNTAX
= FALSE

PURPOSE
This constant represent the boolean value for FALSE (0).
Abbreviated as Fa

EXAMPLES
1 IF v = FALSE THEN
2 PRINT " V is false !"
3 ENDIF

450
 15.190 FILE (storage)

15.190 FILE (storage)

SYNTAX
FILE source [AS target]

PURPOSE
The FILE command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element.
The basic syntax requires indicating the name of the source file that
will be inserted into the medium. If you don’t want to use the same
name, you can indicate an alias (AS target).
See also BEGIN STORAGE
Abbreviated as FILE

EXAMPLES
1 FILE " examples / data . dat "
2 FILE " sprites . png " AS " sprites . dat "

451
 15 Keywords

15.191 FILL (array)

SYNTAX
FILL v1 WITH value[,v2 WITH value[,...]]

PURPOSE
The FILL command allows you to fill an array with a specific value.
Abbreviated as Fil

EXAMPLES
1 DIM a (42) AS BYTE
2 FILL a WITH 1

452
 15.192 FILL (instruction)

15.192 FILL (instruction)

SYNTAX
FILL x,y,w,h,char,color

PURPOSE
The FILL command allows you to fill the screen with a particular char-
acter.

Abbreviated as Fil
EXAMPLES
1 FILL 0 , 0 , COLUMNS / 2 , ROWS / 2 , ASC ( ’A ’)

453
 15 Keywords

15.193 FIND PORT

SYNTAX
port = FIND PORT( sessionId, username, application )

PURPOSE
The FIND PORT function is needed to find out a port where to send
message. To send a message, we need to know the address of that
message port. A message box is identified by a unique identifier, called
portId. So the first useful operation is to find out the port id to use
to send the message. This is exactly the purpose of this function.
So basically three pieces of information are needed to identify that
mailbox. First of all, you need an identifier that allows the user to be
recognized by the DOJO server (sessionId). Secondly, you need to
know the identifier of the user who owns that mailbox (username).
Finally, it is essential to know the name of the application on whose
behalf we are looking for the mailbox (application).
Alias for DOJO FIND PORT

Abbreviated as FndPrt
AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = FIND ( sessionId , " user2 " , " testApp " )

454
 15.194 FIRE (constant)

15.194 FIRE (constant)

SYNTAX
= FIRE

PURPOSE
Return the bitmask for joystick’s fire bit.
Alias for JOY FIRE (constant)

Abbreviated as Fi
EXAMPLES
1 x = FIRE

455
 15 Keywords

15.195 FIRE (function)

SYNTAX
= FIRE( port )

PURPOSE
Read the joystick port and check for ”fire button” bit.
Abbreviated as Fi

EXAMPLES
1 x = FIRE (0)

456
 15.196 FLIP (function)

15.196 FLIP (function)

SYNTAX
= FLIP( string )

PURPOSE
The FLIP function simply reverses the order of the characters held in
the parameter.

Abbreviated as Fl
EXAMPLES
1 x = FLIP ( " test " )

457
15 Keywords

15.197 FLIP IMAGE

SYNTAX

FLIP IMAGE resource [X|Y|XY|YX]

FLIP IMAGE resource FRAME frame [X|Y|XY|YX]
FLIP IMAGE resource STRIP sequence FRAME frame [X|Y|XY|YX]
FLIP [X|Y|XY|YX] IMAGE resource
FLIP [X|Y|XY|YX] IMAGE resource FRAME frame
FLIP [X|Y|XY|YX] IMAGE resource STRIP sequence FRAME frame
FLIP IMAGE resource DIRECTION direction
FLIP IMAGE resource FRAME frame DIRECTION direction
FLIP IMAGE resource STRIP sequence FRAME frame DIRECTION direction
FLIP DIRECTION direction IMAGE resource
FLIP DIRECTION direction IMAGE resource FRAME frame
FLIP DIRECTION direction IMAGE resource STRIP sequence FRAME
frame

PURPOSE
This command allows you to flip an image on the same image, along the
X axis or the Y axis. The programmer can flip a single image (IMAGE), a
frame of a series of images (IMAGES) or a frame of a pose of a sequence
of images (SEQUENCES). In all cases the syntax changes slightly.
It is possible to flip an image either programmatically, directly indicating
the X or Y direction, or by delegating these operations to the value of
a variable. In this case, this value will be preceded by the DIRECTION
keyword. Acceptable values are 1 for the horizontal direction, 2 for the
vertical direction, 3 for both directions.
Abbreviated as FlIm
AVAILABLE ON

458
 15.197 FLIP IMAGE

atari atarixl c128 c64 c64reu coco coco3 cpc d32 d64 mo5 msx1
plus4 to8
EXAMPLES
1 FLIP X IMAGE object

459
 15 Keywords

15.198 FLOAT (data type)

SYNTAX
... AS FLOAT

PURPOSE
The FLOAT is a data type that allow to store a floating point number.
Abbreviated as Ft

EXAMPLES
1 DIM numero AS FLOAT

460
 15.199 FONT HEIGHT (constant)

15.199 FONT HEIGHT (constant)

SYNTAX
= FONT HEIGHT

PURPOSE
This function allows you to obtain the height of the current font, ex-
pressed in pixels. The height depends on the currently selected graphics
mode, and it can change at runtime.

There is also a compile-level function for this keyword, which is called

when the value is used to initialize a constant. In this case, the value is
that taken from inspecting the instructions at the time of compilation.
See also FONT WIDTH (constant)

Abbreviated as FntHg
EXAMPLES
1 fontSize = FONT HEIGHT

461
 15 Keywords

15.200 FONT LOAD

SYNTAX
FONT LOAD filename [TO index]

PURPOSE
The FONT LOAD command allows you to load an image and to convert
it into a font.

The command support a set of modern image format, like:

* JPEG baseline & progressive * PNG 1/2/4/8/16-bit-per-channel *
TGA * BMP (non-1bpp, non-RLE) * PSD (composited view only, no
extra channels, 8/16 bit-per-channel) * GIF * HDR (radiance rgbE
format) * PIC (Softimage PIC) * PNM (PPM and PGM binary only)

The image will be converted into a way that can be efficiently drawn
on the screen using the default characters.
It is also possible to indicate the index from which to start loading the
various characters. The index is not the ASCII code but the screen
code.

Alias for LOAD TILES, TILES LOAD

Abbreviated as FntLd
EXAMPLES
1 FONT LOAD " digit0 . png " TO 48

462
 15.201 FONT WIDTH (constant)

15.201 FONT WIDTH (constant)

SYNTAX
= FONT WIDTH

PURPOSE
This function allows you to obtain the width of the current font, ex-
pressed in pixels. The width depends on the currently selected graphics
mode, and it can change at runtime.

There is also a compile-level function for this keyword, which is called

when the value is used to initialize a constant. In this case, the value is
that taken from inspecting the instructions at the time of compilation.
See also FONT HEIGHT (constant)

Abbreviated as FntWd
EXAMPLES
1 fontSize = FONT WIDTH

463
 15 Keywords

15.202 FOR...NEXT

SYNTAX
FOR var = start TO end [ STEP increment ]
...
NEXT [var]

PURPOSE
The FOR...NEXT is a basic tool for executing a block of code a specified
number of times. It is a control structure that creates a loop, which
is a segment of code that is repeated until a certain condition is met.
Once inside the loop, the index used to loop can be read and modified
by the program as if it is a normal variable.
Normally, the index counter is increased by 1 unit at every turn of a
FOR...NEXT loop. When the current value exceeds that of the last
number specified, the loop is terminated. STEP is used to change the
size of increase in the index value.
The FOR...NEXT loop is ideal for performing the same operation a spe-
cific number of times. It can be used to create tables of values, such
as a multiplication table. It is often used in algorithms that require
repeated calculations, such as calculating the factorial of a number.
Generally speaking, you can use the FOR...NEXT when you know the
number of iterations in advance, want to perform a sequence of opera-
tions repetitively and you need a simple and effective control structure.
See also DO...LOOP, WHILE...WEND, REPEAT...UNTIL

Abbreviated as FoNx
EXAMPLES
1 i = 0
2 FOR i = 1 TO 100 STEP 2

464
 15.202 FOR...NEXT

3 PRINT i
4 NEXT

465
 15 Keywords

15.203 FORBID

SYNTAX
FORBID

PURPOSE
In some situations, it is necessary to ensure that a sequence of opera-
tions is executed atomically, without interruption. The FORBID instruc-
tion plays a crucial role in this way, offering the programmer a way to
take full control of the system’s execution, at least temporarily.
In simple terms, FORBID blocks any attempt by ugBASIC to pass exe-
cution from one task to another. This means that the task that called
FORBID will continue to execute its code without interruption until a
corresponding call to ALLOW is made. The FORBID ensures that a se-
quence of critical operations is executed indivisibly, without interference
from other tasks. This gives the programmer granular control over the
system’s execution.
Abbreviated as Fd

EXAMPLES
1 PARALLEL PROCEDURE test
2 FORBID
3 ’ busy waiting , multitasking is suspended !
4 FOR i =0 TO 1000: WAIT 1 MS : NEXT i
5 ALLOW
6 END PROC

466
 15.204 FRAME

15.204 FRAME

SYNTAX
= FRAME(images)

PURPOSE
Alias for FRAMES, IMAGES COUNT, IMAGE COUNT
Abbreviated as Fr

EXAMPLES
1 animazione := LOAD ATLAS (" images . png ") FRAME SIZE (16 , 16)
2 FOR i = 0 TO FRAME ( animazione )
3 PRINT " frame "; i
4 NEXT

467
 15 Keywords

15.205 FRAMES

SYNTAX
= FRAMES(images)

PURPOSE
This function allows you to obtain the number of frames that make up
a set of images (ATLAS). If applied to a single image resource (IMAGE),
however, it always returns 1. The value is obtained by retrieving it from
the resource itself, and therefore is constant for the entire duration of
the execution.
There is also a compile-level function for this keyword, which is called
when the value is used to initialize a constant. In this case, the value is
that taken from inspecting the instructions at the time of compilation.

Alias for FRAME, IMAGES COUNT, IMAGE COUNT, FRAMES COUNT, FRAME
COUNT
Abbreviated as Frs
EXAMPLES
1 animazione := LOAD ATLAS (" images . png ") FRAME SIZE (16 , 16)
2 FOR i = 0 TO FRAMES ( animazione )
3 PRINT " frame "; i
4 NEXT

468
 15.206 FRAMES COUNT

15.206 FRAMES COUNT

SYNTAX
= FRAMES COUNT(images)

PURPOSE
Alias for FRAME, IMAGES COUNT, FRAMES
Abbreviated as FrsC%

EXAMPLES
1 animazione := LOAD IMAGES (" images . png ") FRAME SIZE (16 , 16)
2 FOR i = 0 TO FRAMES COUNT ( animazione )
3 PRINT " frame "; i
4 NEXT

469
 15 Keywords

15.207 FREE

SYNTAX
... = FREE

PURPOSE
Retrieves the free space still available for strings, in terms of bytes. This
is how many characters are still available to be stored. The maximum
value when calling this function is that indicated by the DEFINE STRING
SPACE statement. The default value for string storage is 1024 bytes.
The command implicitly invokes garbage collection.
Abbreviated as Fre
EXAMPLES
1 PRINT FREE

470
 15.208 GET

15.208 GET

SYNTAX
GET var

PURPOSE
Alias for INKEY
Abbreviated as Ge

EXAMPLES
1 GET tasto

471
 15 Keywords

15.209 GET BITMAP

SYNTAX
GET BITMAP var FROM [x], [y]

PURPOSE
The purpose of the GET BITMAP command is to store the contents of
the screen in a variable, just the bitmap component so without color
component. The syntax requires the point from which to start storing
the image, whose dimensions are implicitly obtained from the variable.
This command ssupports ATLAS and SEQUENCE version, so you can
acquire a single frame from the screen.
See also GET IMAGE

Abbreviated as GeBm
EXAMPLES
1 background = NEW IMAGE (16 , 16)
2 GET BITMAP background FROM 0 , 0

472
 15.210 GET IMAGE

15.210 GET IMAGE

SYNTAX
GET IMAGE var FROM [x], [y]
GET (x1,y1) - (x2,y2), var[, G]

PURPOSE
The purpose of the GET IMAGE command is to store the contents of the
screen in a variable. The first syntax is where the programmer provides
the coordinates of the rectangle to be stored. This syntax will store
only the bitmap of the image. You need to give the G option if you
want to store color component, too.
The second, instead, only requires the point from which to start storing
the image, whose dimensions are implicitly obtained from the variable.
The color component is acquired implictly. The GET IMAGE syntax is
the only one that supports ATLAS and SEQUENCE version, so you can
acquire a single frame from the screen.
See also GET BITMAP

Abbreviated as GeIm
AVAILABLE ON
atari c128 c64 coco coco3 coleco d32 d64 mo5 msx1 plus4 sc3000
sg1000 vic20 zx

EXAMPLES
1 background = NEW IMAGE (16 , 16)
2 GET IMAGE background FROM 0 , 0

473
 15 Keywords

15.211 GET MESSAGE

SYNTAX
port = GET MESSAGE( portId )

PURPOSE
The command GET MESSAGE fetch the message from the given port.
Note that the message port behaves like a queue, that is, the first
message that is inserted is the first that is retrieved. Therefore, if a
program sends three messages in a row to the attention of the port of
another, the receiving program will receive the three messages in the
same order.
Obviously, if several programs do the same thing, the messages will be
interspersed but, in the end, they will be in the same order.

Alias for DOJO GET MESSAGE

Abbreviated as GeMsg
AVAILABLE ON

c64 c64reu coco coco3

EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = FIND ( sessionId , " user2 " , " testApp " )
3 msg = GET MESSAGE ( port )

474
 15.212 GLOBAL

15.212 GLOBAL

SYNTAX
GLOBAL var[, var[, ...]]
GLOBAL string
GLOBAL var1[, var2[, ...] ]
GLOBAL "string1"[, "string2"[, ...] ]

PURPOSE

When you write a program, variables are like containers that store data.
Depending on where you declare them, these variables can have different
”scopes,” meaning they can be accessed from different parts of your
code. The GLOBAL command allows to define a variable as accessible
from everywhere.

You should use GLOBAL to store parameters that do not change during
program execution, to share the state between different parts of your
code, and generally to improve performance, but it is important to weigh
the pros and cons carefully. In general, it is a good idea to limit the use
of global variables and use local variables whenever possible.

You can use the name of variables to make them global, or a string
with a ”pattern” to follow, to choose if a variable will be global or not.
Pattern uses ”wildcard” to match any letter in name of the variables.
This keyword sets up a list of variables that can be accessed from abso-
lutely anywhere in your program. This is a simplified single command,
designed to be used without the need for an explicit SHARED statement
in procedure definitions.
There is a facility of using strings in procedure definitions. As with
disc names, the ”wild card” characters * and ? can also be included.
In this case, the * character is used to mean ”match this with any

475
 15 Keywords

list of characters in the variable name, until the next control character
is reached”, and the ? character means ”match this with any single
character in the variable name”.
GLOBAL or SHARED should be employed before the first use of the vari-
able. Only strings may be used for this technique.
See also SHARED
Abbreviated as Gb
EXAMPLES
1 GLOBAL var42
2 GLOBAL " a *"
3 GLOBAL test
4 GLOBAL " a *" , b , "* c "

476
 15.213 GLOBAL CONST

15.213 GLOBAL CONST

SYNTAX
[POSITIVE] GLOBAL CONST identifier = value
GLOBAL CONST identifier IN (min,max) = value
GLOBAL CONST identifier IN "[" min,max) = value
GLOBAL CONST identifier IN (min,max "]" = value
GLOBAL CONST identifier IN "[" min,max "]"" = value

PURPOSE
Alias for SHARED, CONST SHARED, SHARED CONST, CONST GLOBAL
Abbreviated as GbC#
EXAMPLES
1 GLOBAL CONST x = 42
2 POSITIVE GLOBAL CONST y = -42: ’ this raises an error !
3 GLOBAL CONST width IN (0 ,320] = 128

477
 15 Keywords

15.214 GOLD (constant)

SYNTAX
= GOLD

PURPOSE
This keyword represents the color gold. Depending on the methodology
and technique, as well as the available hardware, it can correspond to a
specific color in the RGB space. However, not all computers have this
color. In which case, it is approximated by the closest color available,
which is usually also used in decoding images to identify the color to
use.
Abbreviated as Gd

EXAMPLES
1 PEN GOLD

478
 15.215 GOSUB

15.215 GOSUB

SYNTAX

GOSUB label

PURPOSE
The GOSUB command allows you to ”jump” to a specific part of the
program, execute a set of instructions and then return exactly to the
point where you started.
It allows you to break a program into smaller, more manageable blocks
of code, improving readability and maintenance. A subroutine can
be called multiple times from different parts of the program, avoid-
ing rewriting the same code multiple times. It helps organize the flow
of the program, making it clearer and easier to follow.
While GOTO allows an unconditional jump to any line of the program,
GOSUB is more structured and allows a return to the starting point. In
general, GOSUB is considered a more powerful and flexible tool than
GOTO, as it allows for better organization of the code.

It is possible to nest subroutines, but it is important to make sure that

each GOSUB has its corresponding RETURN. So, a common mistake is to
forget to put RETURN at the end of a subroutine, causing unpredictable
behavior of the program.
Subroutines are often implemented through functions and procedures,
which offer more advanced functionality and more rigorous management
of variable scope.
See also RETURN, POP
Abbreviated as Gs

479
 15 Keywords

EXAMPLES
1 GOSUB leggiTasti

480
 15.216 GOTO

15.216 GOTO

SYNTAX
GOTO label
GOTO number

PURPOSE
The GOTO command is a statement that allows you to jump uncondi-
tionally to another part of the program. In practice, instead of executing
the instructions in sequence, the program ”jumps” directly to the line
indicated by the GOTO command.
Despite its simplicity, indiscriminate use of the GOTO command can lead
to several problems. It can make the code very difficult to follow and
understand, creating so-called ”spaghetti code”. If a program con-
tains many unconditional jumps, it can become very difficult to find
the source of an error. Frequent use of GOTO tends to create a poorly
structured flow of control that is difficult to maintain.
The ugBASIC offers more sophisticated and readable control structures,
such as: IF...THEN...ELSE, FOR...NEXT, DO...LOOP, and so on.
These structures make the code clearer and make it easier to manage
the flow of control.
In some specific cases, however, the use of GOTO can be justified, for
example in very specific situations, a GOTO can be used to exit a nested
loop more efficiently. In some cases, a GOTO can be used to handle
errors in the most direct way. In general, it is advisable to avoid the use
of GOTO and prefer more modern control structures. A well-structured
and readable code is easier to maintain and to change over time.
Abbreviated as Go
EXAMPLES

481
 15 Keywords

1 GOTO nuovaEt ichetta

2 GOTO 42

482
 15.217 GR LOCATE

15.217 GR LOCATE

SYNTAX
GR LOCATE [x], [y]

PURPOSE
The GR LOCATE allows you to position the graphics cursor in a spe-
cific position on the screen, thus preparing the ground for subsequent
drawing operations, such as printing text, drawing lines or shapes.

Before drawing lines, rectangles, or other shapes, you must position the
graphics cursor at the starting point of the shape. By combining GR
LOCATE with other graphics commands, you can create animations by
moving objects around the screen.

Obviously, the coordinate system and screen size depend on the graphics
mode selected with the BITMAP ENABLE or SCREEN commands. The ug-
BASIC offers other graphics functions, such as PLOT for drawing points,
LINE for drawing lines, and many more.
Abbreviated as GRLc

EXAMPLES
1 GR LOCATE 100 ,10

483
 15 Keywords

15.218 GRAPHIC

SYNTAX
GRAPHIC

PURPOSE
Do a quickly initialization with the high resolution graphics mode.
Abbreviated as Gr

EXAMPLES
1 GRAPHIC

484
 15.219 GRAY (constant)

15.219 GRAY (constant)

SYNTAX
= GRAY

PURPOSE
Alias for GREY (constant)
Abbreviated as Gy

EXAMPLES
1 PEN GRAY

485
 15 Keywords

15.220 GREEN (constant)

SYNTAX
= GREEN

PURPOSE
This keyword represents the color green. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (0,204,85). However,
not all computers have this color. In which case, it is approximated by
the closest color available, which is usually also used in decoding images
to identify the color to use.
Abbreviated as Gre

EXAMPLES
1 PEN GREEN

486
 15.221 GREY (constant)

15.221 GREY (constant)

SYNTAX
= GREY

PURPOSE
This keyword represents the color grey. Depending on the methodology
and technique, as well as the available hardware, it can correspond to a
specific color in the RGB space. However, not all computers have this
color. In which case, it is approximated by the closest color available,
which is usually also used in decoding images to identify the color to
use.
Alias for GRAY (constant)

Abbreviated as GREY
EXAMPLES
1 PEN GREY

487
 15 Keywords

15.222 HALT

SYNTAX
HALT

PURPOSE
This instruction stops the program execution, in ”busy” mode. The
implementation is by means of an infinite loop, which is executed when
the instruction is executed. With this expedient, the execution of inter-
rupts will continue without being interrupted while all other operations
will be interrupted, including multithreading.
Abbreviated as Ht
EXAMPLES
1 HALT

488
 15.223 HAS BIT

15.223 HAS BIT

SYNTAX
= value HAS BIT position

PURPOSE
Think of a number as a sequence of switches, each of which can be on
(1) or off (0). Each switch represents a bit. The HAS BIT instruction
will check a bit on (1), by checking the state of a specific switch within
this sequence. The parameter position refers to the bit position inside
the data. This value is zero based, and starts from the less significative
bit and go on.
Alias for IS, IS NOT

See also HAS NOT BIT

Abbreviated as HASBt
EXAMPLES
1 IF x HAS BIT 2 THEN : PRINT " bit 2 is 1!": ENDIF

489
 15 Keywords

15.224 HAS NOT BIT

SYNTAX
= value HAS NOT BIT position

PURPOSE
Think of a number as a sequence of switches, each of which can be
on (1) or off (0). Each switch represents a bit. The HAS NOT BIT
instruction will check a bit off (0), by checking the state of a specific
switch within this sequence. The parameter position refers to the bit
position inside the data. This value is zero based, and starts from the
less significative bit and go on.
Alias for IS, IS NOT

See also HAS NOT BIT

Abbreviated as HASNtBt
EXAMPLES
1 IF x HAS NOT BIT 2 THEN : PRINT " bit 2 is 0": ENDIF

490
 15.225 HEIGHT (constant)

15.225 HEIGHT (constant)

SYNTAX
= HEIGHT

PURPOSE
Alias for SCREEN HEIGHT.
Alias for SCREEN HEIGHT (constant)

Abbreviated as Hg
EXAMPLES
1 IF HEIGHT > 128 THEN : PRINT " At least 128 pixels !!": ENDIF

491
 15 Keywords

15.226 HEX

SYNTAX
= HEX(expression)

PURPOSE
The HEX statement is used to convert a decimal number to a hexadec-
imal number. Hexadecimal, or base 16, is a numbering system that
uses 16 digits (0 through 9 and the letters A through F) to represent
numbers.
This system is widely used in computing, especially to represent memory
addresses, colors, and character codes. Moreover, it is a concise way
of representing binary numbers, which are the basis of how computers
work, and bit-level operations are often easier to display and manipulate
in hexadecimal.
The expression is the value you want to convert to hexadecimal, and
it must be an integer value. The HEX statement will return a string
representing the hexadecimal value corresponding to the input number.
The length of the returned string depends on the size (in bytes) of
expression.
Alias for $$
Abbreviated as Hx
EXAMPLES
1 x = HEX ( 42 )
2 PRINT HEX ( y )

492
 15.227 HIRES

15.227 HIRES

SYNTAX
HIRES ink, paper

PURPOSE
‘HIRES‘ is used to switch from text to high-resolution graphics mode
and to use the specified colors: ink for the writing color and paper
for the background color (both with values from 0 to SCREEN COLORS).
The graphics memory is deleted and preset with the specified colors.
The color of the screen frame remains unaffected. The selected mode
remains active until it is switched off or changed by a command (MULTI,
CSET or NRM). Important: the color specifications of almost all other
graphics commands that use fg as color parameter refers to the colors
specified here. If the color source 0 is specified in a graphics command,
the color specified for paper is selected; if 1 is specified, the color for
ink is selected; the color specification 2 inverts the controlled pixel (if
in hires mode, otherwise see MULTI).
Abbreviated as Hi

AVAILABLE ON
c128
EXAMPLES
1 HIRES 0 , 1

493
 15 Keywords

15.228 HIT

SYNTAX
= HIT(#sprite)
= HIT(var)

PURPOSE
Verify if a sprite has had a collision with a tile. The result (0 = no
collision, ¡¿ 0 = collision occurred) is returned as result.

Alias for COLLISION.

Alias for COLLISION
AVAILABLE ON

c128 c64
EXAMPLES
1 IF HIT ( starship ) THEN
2 POINT AT (100 ,100)
3 ENDIF

494
 15.229 HOME (constant)

15.229 HOME (constant)

SYNTAX
= HOME

PURPOSE
This constant represent the ”HOME” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Hm
EXAMPLES
1 IF KET STATE ( HOME ) THEN
2 PRINT " HOME has been pressed !"
3 ENDIF

495
 15 Keywords

15.230 HOME (instruction)

SYNTAX
HOME

PURPOSE
The HOME command moves the text cursor back to the top left-hand
corner of the screen in a hurry.

See also LOCATE, AT$, CMOVE

Abbreviated as Hm
EXAMPLES
1 HOME

496
 15.231 HSCROLL

15.231 HSCROLL

SYNTAX
HSCROLL LEFT
HSCROLL SCREEN LEFT
HSCROLL RIGHT
HSCROLL SCREEN RIGHT

PURPOSE

Il comando HSCROLL permette di effettuare lo scrolling orizzontale, sia

di una singola linea che di tutto lo scherrmo, a destra oppure a sinistra.
Abbreviated as Hs
AVAILABLE ON

atari atarixl c128 c64 c64reu coco coco3 coleco cpc d32 d64
mo5 msx1 pc128op plus4 sc3000 sg1000 to8 vic20 zx
EXAMPLES
1 HSCROLL LEFT

497
 15 Keywords

15.232 IF (function)

SYNTAX
= IF (exp, valueTrue, valueFalse )

PURPOSE
The IF function allows you to evaluate whether a certain expression is
TRUE (not 0) or FALSE. (0). Depending on that check, the function will
return the second (if TRUE) or third (if FALSE) argument.

This function evaluates the expression at compile time: it follows that

the return value does not change at runtime. There are three versions
of this function, one for each type of value that can be returned. There
is a version that returns integers, one for floating point numbers, and
one for strings.

This function is particularly useful for carrying out a conditional evalua-

tion of constants which, otherwise, would require evaluation at runtime,
wasting time and occupying useless space.
Abbreviated as If

EXAMPLES
1 pictureToUse = IF ( SCREEN WIDTH > 160 , " large . png " , " small . png "
)

498
 15.233 IF...THEN...ELSE...ELSEIF...ENDIF

15.233 IF...THEN...ELSE...ELSEIF...ENDIF

SYNTAX
IF expression THEN
...
ELSE
...
ENDIF
IF expression THEN
...
ELSEIF expression2 THEN
...
...
ELSE
...
ENDIF
IF expression THEN GOTO number
IF expression THEN number [ELSE number]
IF expression THEN statement

PURPOSE

Implement a conditional jump. This implementation assumes that an

expression passed as a parameter is 0 (for false) and not zero (for true).
In this case, if the expression is zero, it jumps directly to the statement
following the corresponding ENDIF (or ELSE, if present). Otherwise,
the following code will be executed (up to ENDIF or ELSE).

The compiler also accepts a number of variants to the command, which

were however widespread in other BASIC dialects. The first variant is
the one for which the action to be performed is unique, and only an
unconditional jump via GOTO or even as a number immediately after the
THEN. There is also a variant that directly accepts a single command

499
 15 Keywords

after the THEN.

Abbreviated as IfThElEifEi
EXAMPLES
1 IF ( x == 42 ) THEN : x = 0 : ELSE : x = 1 : ENDIF
2 IF ( x == 42 ) THEN : x = 0 : ELSE IF y == 0 THEN : y = 42 :
ELSE : x = 1 : ENDIF
3 IF ( x == 42 ) THEN
4 x = 0
5 ELSE IF y == 0 THEN
6 y = 42
7 ELSE
8 x = 1
9 ENDIF

500
 15.234 IMAGE (data type)

15.234 IMAGE (data type)

SYNTAX
... AS IMAGE

PURPOSE
The IMAGE data type maintains a reference to an image that can be
drawn on the screen

Abbreviated as Im

501
 15 Keywords

15.235 IMAGE (function)

SYNTAX
= IMAGE( resource FRAME num )
= IMAGE( resource STRIP seq FRAME num )
= IMAGE( resource NAMED name )

PURPOSE
The IMAGE command allows you to extract an image from a collection of
images stored in an IMAGES or SEQUENCE variable. Note that extraction
occurs at compile time: therefore, no extra resources are allocated in the
compiled program. This command is intended for all those commands
that need an image to function, but want to exploit a graphic resource
already loaded and optimized. If resource is a TILESET, you can look
for a specific frame by name, unsing the NAMED parameter.
Abbreviated as Im
EXAMPLES
1 starship = IMAGE ( LOAD IMAGES ((" tiles . png ") FRAME 1 )
2 starship = IMAGE ( LOAD SEQUENCE (" tiles . png ") STRIP 1 FRAME 2 )
3 tile = IMAGE ( LOAD TILESET (" tiles . tsx ") NAMED pavimento )

502
 15.236 IMAGE (storage)

15.236 IMAGE (storage)

SYNTAX
IMAGE source [AS target]

PURPOSE
The IMAGE command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
an image. The basic syntax requires indicating the name of the source
file that will be converted and inserted into the medium. If you don’t
want to use the same name, you can indicate an alias (AS target).
Abbreviated as Im
EXAMPLES
1 IMAGE " examples / data . png "
2 IMAGE " sprites . bmp " AS " sprites . dat "

503
 15 Keywords

15.237 IMAGE HEIGHT

SYNTAX
= IMAGE HEIGHT(image)

PURPOSE
This function allows you to obtain the height of a given IMAGE or a
given set of IMAGES. The height is expressed in pixels.

There is also a compile-level function for this keyword, which is called

when the value is used to initialize a constant. In this case, the value is
that taken from inspecting the instructions at the time of compilation.
See also IMAGE WIDTH

Abbreviated as ImHg
EXAMPLES
1 starshipHeig ht = IMAGE HEIGHT ( LOAD IMAGE (" starship . png ") )

504
 15.238 IMAGE LOAD

15.238 IMAGE LOAD

SYNTAX
PURPOSE

Alias for LOAD IMAGE

Abbreviated as ImLd

505
 15 Keywords

15.239 IMAGE WIDTH

SYNTAX
= IMAGE WIDTH(image)

PURPOSE
This function allows you to obtain the width of a given IMAGE or a given
set of IMAGES. The width is expressed in pixels.

There is also a compile-level function for this keyword, which is called

when the value is used to initialize a constant. In this case, the value is
that taken from inspecting the instructions at the time of compilation.
See also IMAGE HEIGHT

Abbreviated as ImWd
EXAMPLES
1 starshipWidth = IMAGE WIDTH ( LOAD IMAGE (" starship . png ") )

506
 15.240 IMAGES (data type)

15.240 IMAGES (data type)

SYNTAX
... AS IMAGES

PURPOSE
Alias for ATLAS
Abbreviated as Ims

507
 15 Keywords

15.241 IMAGES (storage)

SYNTAX
IMAGES source [AS target] FRAME SIZE(width, height)

PURPOSE
The IMAGES command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
an set of images. The basic syntax requires indicating the name of the
source file that will be converted and inserted into the medium. If
you don’t want to use the same name, you can indicate an alias (AS
target).
Abbreviated as Ims

EXAMPLES
1 IMAGES " examples / data . png " FRAME SIZE (16 , 16)
2 IMAGES " sprites . bmp " AS " sprites . dat " FRAME SIZE (16 , 16)

508
 15.242 IMAGES COUNT

15.242 IMAGES COUNT

SYNTAX
= IMAGES COUNT(images)

PURPOSE
Alias for FRAMES, IMAGES COUNT, IMAGE COUNT, FRAMES COUNT, FRAME
COUNT

Abbreviated as ImsC%
EXAMPLES
1 animazione := LOAD IMAGES (" images . png ") FRAME SIZE (16 , 16)
2 FOR i = 0 TO IMAGES COUNT ( animazione )
3 PRINT " frame "; i
4 NEXT

509
15 Keywords

15.243 IMAGES LOAD

SYNTAX
PURPOSE

Alias for LOAD ATLAS, ATLAS LOAD, LOAD IMAGES

Abbreviated as ImsLd

510
 15.244 IN

15.244 IN

SYNTAX
= IN(port)

PURPOSE
The IN command is used to read a value from a specific input/output
(I/O) port. The port parameter indicates the exact address of the
I/O port from which you want to acquire the data. The port address
varies depending on the architecture of the computer and the connected
peripheral.
When the program encounters the IN instruction, it stops executing
and reads the binary value present on the specified port. The value
read from the port is converted into a numeric format understandable
by the program and is assigned to the value variable.
The IN command is often used to read data from sensors connected to
I/O ports, such as temperature, humidity, light sensors, etc. It can be
used to control the status of external devices, such as motors, relays,
displays, etc. In combination with other instructions, the IN command
can be used to implement serial communication with other devices.
Abbreviated as In
AVAILABLE ON
c128z coleco cpc msx1 sc3000 sg1000 vg5000 zx

EXAMPLES
1 x = IN ( & HBC00 )

511
 15 Keywords

15.245 INC

SYNTAX
INC var

PURPOSE
The INC command is used to increment (i.e. increase) the value of a
numeric variable by one. It is a quick and concise way to add 1 from the
value contained in a variable. In place of variable, enter the name of
the numeric variable you want to increment.
The INC command is actually a shorthand for the adding operation, as
writing num=num+1. However, DEC is often preferred because of its more
concise syntax and its specific increment function. The INC command
can only be applied to numeric variables (integer).

See also DEC

EXAMPLES
1 INC score

512
 15.246 INCLUDE

15.246 INCLUDE

SYNTAX
INCLUDE "filename"

PURPOSE
The INCLUDE command allows you to insert a source from an external
file. In practice, what happens is that the content of the file, without
any interpretation, is copied ”as is” at the point where the statement
was inserted. All variables and scopes will be maintained.

513
 15 Keywords

15.247 INK

SYNTAX
INK color

PURPOSE
Alias for PEN
Abbreviated as Ik

EXAMPLES
1 INK 4

514
 15.248 INKEY

15.248 INKEY

SYNTAX
= INKEY$

PURPOSE
The ”INKEY’ (or INKEY$) capture a single character typed by the user
without having to press enter. In other words, the program is ”listening”
to the keyboard and, as soon as a key is pressed, ”captures” it and stores
it in a variable.
Unlike the INPUT command, which requires the user to press enter after
typing, INKEY reads the character as soon as it is pressed. If no key
has been pressed, INKEY$ returns an empty string (””). The captured
character is stored in a string variable.

It is used to create interactive games where the user can control the
character or objects by pressing specific keys, to create text menus
where the user can select an option by pressing a letter or number or
to create programs that respond to external events, such as pressing a
key to start or stop an action.

The INKEY$ only reads one character at a time. To read a complete

string, you must use other commands or techniques. The command
does not usually display the pressed character on the screen.
See also SCANCODE

Abbreviated as Iky
EXAMPLES
1 IF INKEY$ = " A " THEN
2 PRINT " A has been pressed !"
3 ENDIF

515
15 Keywords

15.249 INPUT (function)

SYNTAX
= INPUT$(number)
INPUT [prompt];v1[;v2[;...]
INPUT [prompt];v1[,v2[,...]
INPUT [prompt],v1[;v2[;...]
INPUT [prompt],v1[,v2[,...]

PURPOSE
The INPUT$ function reads a string of characters specified on the key-
board and stores them in a variable. Unlike INPUT, which pauses and
waits until the user presses wnter, INPUT$ reads a fixed number of
characters without prompting for an enter.

It is used to read barcodes, serial numbers, or other fixed character se-

quences, and to create simpler and more direct user interfaces, avoiding
the need to press enter after each character.
INPUT$ always reads the specified number of characters, even if the user
types fewer than that. It does not perform any checks on the validity
of the characters entered.
The INPUT command allows you to ask the user to enter data, such
as numbers or text, while your program is running. When your pro-
gram encounters an INPUT statement, it stops executing and displays a
prompt (usually the name of the variable) that invites the user to enter
a value. The user types the value and presses Enter. The entered value
is then stored in the specified variable.
Make sure the variable type matches the type of data you want to
capture (e.g. a numeric variable for a number, a string variable for
text). The message is optional but highly recommended to make it

516
 15.249 INPUT (function)

clear to the user what to enter. After entering the value, the user must
always press Enter to confirm.
See also INPUT (instruction), INPUT (function)

Abbreviated as Ip
EXAMPLES
1 IF INPUT$ (3) = "123" THEN
2 PRINT "123 has been pressed !"
3 ENDIF
4 INPUT " Type a string " , a$
5 PRINT " The string was "; a$

517
 15 Keywords

15.250 INSERT (constant)

SYNTAX
= INSERT

PURPOSE
This constant represent the ”INSERT” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Ins
EXAMPLES
1 IF KET STATE ( INSERT ) THEN
2 PRINT " INSERT has been pressed !"
3 ENDIF

518
 15.251 INSERT (function)

15.251 INSERT (function)

SYNTAX
= INSERT( string, alt, pos )

PURPOSE
The INSERT command allows you to insert a substring into an existing
string, at a specific position that you specify. INSERT inserts the charac-
ter string string (first argument) into the character string alt (second
argument) starting at the position pos (third argument), whereby the
counting starts with 1. The resulting character string is as long as the
sum of the two individual character strings.
You can use INSERT to join strings more precisely than simple concate-
nation with the + symbol. You can insert spaces, special characters,
or other elements to format strings to your liking. You can correct ty-
pos, add or remove text precisely. You can build complex strings by
combining static and variable parts.
The position pos you specify must be an integer between 1 and the
length of the main string plus 1. INSERT creates a copy of the final
string.
Abbreviated as Ins
EXAMPLES
1 c$ = INSERT ( a$ , b$ ,9)

519
 15 Keywords

15.252 INSERT (instruction)

SYNTAX
INSERT string, x, y, w, h, c

PURPOSE
The INSERT command can draw frames on the screen in text mode. The
appearance of the frame is determined by the first parameter string.
It must contain a character string that is exactly nine characters long
and consists of the characters that define the frame: top left corner,
top edge, top right corner, left edge, fill character, right edge, bottom
left corner, bottom edge, bottom right corner. If this string is too long
or too short, the behaviour is undefined.
Abbreviated as Ins

EXAMPLES
1 INSERT "+ -+| |+ -+" , 0 , 0 , 10 , 10 , RED

520
 15.253 INST

15.253 INST

SYNTAX
= INST( string, alt, pos )

PURPOSE
The INST function overwrites the characters of the string ”alt’ with the
character string string (first argument) in the character string alt
(second argument) from the position pos (third argument), whereby the
counting starts with 1. The length of the character string altstring
does not change.
Abbreviated as Inx
EXAMPLES
1 c$ = INST ( a$ , b$ ,9)

521
 15 Keywords

15.254 INSTR

SYNTAX
= INSTR( text, searched [, start] )

PURPOSE
This function can be called to search through strings for individual
characters or sub-strings: it allows you to search for all instances of one
string inside another. The string is searched for the first occurrence of
the second strings. If it is found, its location will be reported in the
form of the number of characters from the left-hand side of the searched
string. If the search is unsuccessful, a result of zero will be given.
Normally, the search will begin from the first character at the extreme
left-hand side of the host string, but you can specify an (optional)
number of characters from the beginning of the searched string. The
optional start-of-search position can range from one to the maximum
number of characters in the searched string to be searched.
Alias for PLACE

Abbreviated as Ist
EXAMPLES
1 x = INSTR ( " ugBASIC " , " A " )
2 x = INSTR ( " ugBASIC " , " A " , 2 )

522
 15.255 INSTRUMENT

15.255 INSTRUMENT

SYNTAX
INSTRUMENT #instrument [ON #channels]
INSTRUMENT name [ON #channels]

PURPOSE
This command allows you to select one of the available tools. Instru-
ments can be set for all voices, or for a set of particular voices.

Abbreviated as Inst
AVAILABLE ON
c128 c64 c64reu

EXAMPLES
1 INSTRUMENT #42 ON %001
2 INSTRUMENT SHAMISEN

523
 15 Keywords

15.256 INT (data type)

SYNTAX
... AS INT

PURPOSE
The INT is a data type that allow to store a signed 16-bit word.
Alias for INTEGER (data type), SIGNED WORD (data type)

Abbreviated as Int
EXAMPLES
1 DIM parolaLunga AS INT

524
 15.257 INT (function)

15.257 INT (function)

SYNTAX
= INT(value)

PURPOSE
The INT command is a mathematical function that rounds a FLOAT to
the smallest INT number. In other words, it cuts off the decimal part
of the number, returning only the whole part.

If you apply INT to a number that is already an integer, the result will
be the same number. INT is rounded down, so for negative numbers it
means taking the largest integer (in absolute value) less than or equal
to the original number.

INT is useful when you need to work only with the integer part of
a number. It can be used in combination with other mathematical
operations to perform more complex calculations. Sometimes you need
to convert a FLOAT to an integer in order to use it in certain functions
or data structures.

Abbreviated as Int
EXAMPLES
1 x = 1.5
2 PRINT INT ( x ) : ’ It prints 1

525
 15 Keywords

15.258 INTEGER (data type)

SYNTAX
... AS INTEGER

PURPOSE
Alias for INT (data type), SIGNED WORD (data type)
Abbreviated as INTEGER

EXAMPLES
1 DIM parolaLunga AS INTEGER

526
 15.259 IS

15.259 IS

SYNTAX
= value IS position

PURPOSE
Alias for HAS BIT, HAS NOT BIT
See also IS NOT

EXAMPLES
1 IF x IS 2 THEN : PRINT " bit 2 is 1!": ENDIF

527
 15 Keywords

15.260 IS NOT

SYNTAX
= value IS NOT position

PURPOSE
Alias for HAS NOT BIT
See also IS BIT

Abbreviated as ISNt
EXAMPLES
1 IF x IS NOT 2 THEN : PRINT " bit 2 is 0": ENDIF

528
 15.261 JDOWN

15.261 JDOWN

SYNTAX
= JDOWN( port )

PURPOSE
Read the joystick port and check for ”direction down” bit.
Abbreviated as Jd

EXAMPLES
1 x = JDOWN (0)

529
 15 Keywords

15.262 JFIRE

SYNTAX
= JFIRE( port )

PURPOSE
Read the joystick port and check for ”fire button” bit.
Abbreviated as Jf

EXAMPLES
1 x = JFIRE (0)

530
 15.263 JLEFT

15.263 JLEFT

SYNTAX
= JLEFT( port )

PURPOSE
Read the joystick port and check for ”direction left” bit.
Abbreviated as Jl

EXAMPLES
1 x = JLEFT (0)

531
 15 Keywords

15.264 JOY

SYNTAX
= JOY( port )

PURPOSE
Read the value from the joystick port.
Abbreviated as Jy

EXAMPLES
1 x = JOY (0)

532
 15.265 JOY COUNT (constant)

15.265 JOY COUNT (constant)

SYNTAX
= JOY COUNT

PURPOSE
Read the number of joysticks installed into the system.
Alias for JOYCOUNT

Abbreviated as JyC%
EXAMPLES
1 x = JOY COUNT

533
 15 Keywords

15.266 JOY DOWN (constant)

SYNTAX
= JOY DOWN

PURPOSE
This constant represents the bitmask to use to identify the ”down di-
rection” bit for the value returned by the JOY function.

Abbreviated as JyDw
EXAMPLES
1 IF JOY (0) AND JOY DOWN THEN
2 PRINT " DOWN !"
3 ENDIF

534
 15.267 JOY FIRE (constant)

15.267 JOY FIRE (constant)

SYNTAX
= JOY FIRE

PURPOSE
Alias for FIRE (constant)
Abbreviated as JyFi

EXAMPLES
1 x = JOY FIRE

535
 15 Keywords

15.268 JOY LEFT (constant)

SYNTAX
= JOY LEFT

PURPOSE
This constant represents the bitmask to use to identify the ”left direc-
tion” bit for the value returned by the JOY function.

Abbreviated as JyLf
EXAMPLES
1 IF JOY (0) AND JOY LEFT THEN
2 PRINT " LEFT !"
3 ENDIF

536
 15.269 JOY RIGHT (constant)

15.269 JOY RIGHT (constant)

SYNTAX
= JOY RIGHT

PURPOSE
This constant represents the bitmask to use to identify the ”right di-
rection” bit for the value returned by the JOY function.

Abbreviated as JyRg
EXAMPLES
1 IF JOY (0) AND JOY RIGHT THEN
2 PRINT " RIGHT !"
3 ENDIF

537
 15 Keywords

15.270 JOY UP (constant)

SYNTAX
= JOY UP

PURPOSE
This constant represents the bitmask to use to identify the ”up direc-
tion” bit for the value returned by the JOY function.

Abbreviated as JyUP
EXAMPLES
1 IF JOY (0) AND JOY UP THEN
2 PRINT " UP !"
3 ENDIF

538
 15.271 JOY X

15.271 JOY X

SYNTAX
= JOY X( port )

PURPOSE
Read the horizontal axys of an analogical joystick, if it is present. A
negative value means ”left” while a positive one means ”right”. The
value near 0 means ”no direction”.

Alias for JOYX

Abbreviated as JyX
AVAILABLE ON

coco coco3 d32 d64

EXAMPLES
1 x = JOY X (0)

539
 15 Keywords

15.272 JOYCOUNT

SYNTAX
= JOYCOUNT

PURPOSE
Read the number of joysticks installed into the system.
Alias for JOY COUNT

Abbreviated as Jyc
EXAMPLES
1 x = JOYCOUNT

540
 15.273 JOYX

15.273 JOYX

SYNTAX
= JOYX( port )

PURPOSE
Alias for JOY X
Abbreviated as Jyx

AVAILABLE ON
coco coco3 d32 d64
EXAMPLES
1 x = JOYX (0)

541
 15 Keywords

15.274 JOYY

SYNTAX
= JOY Y( port )
= JOYY( port )

PURPOSE
Read the vertical axys of an analogical joystick, if it is present. A
negative value means ”up” while a positive one means ”down”. The
value near 0 means ”no direction”.
Alias for JOYY, JOY Y
Abbreviated as Jyy

AVAILABLE ON
coco coco3 d32 d64
EXAMPLES
1 y = JOY Y (0)
2 y = JOYY (0)

542
 15.275 JRIGHT

15.275 JRIGHT

SYNTAX
= JRIGHT( port )

PURPOSE
Read the joystick port and check for ”direction right” bit.
Abbreviated as Jr

EXAMPLES
1 x = JRIGHT (0)

543
 15 Keywords

15.276 JUP

SYNTAX
= JUP( port )

PURPOSE
Read the joystick port and check for ”direction up” bit.
Abbreviated as Ju

EXAMPLES
1 x = JUP (0)

544
 15.277 KEY PRESSED

15.277 KEY PRESSED

SYNTAX
= KEY PRESSED(keycode)

PURPOSE
The KEY PRESSED command allows you to know the pressing state of
a single specific key, during the ”duty cycle” of the keyboard driver.
The reading is deferred: therefore, it is possible to detect the pressing
of just one key at a time but there is no possibility that the pressing of
the key is not detected.
The parameter of this function is the so-called ”keycode”. Each key
on the target computer’s keyboard is encoded by a value, which is
specific to the hardware being considered. It should not be confused
with the ASCII code, which is a representation shared between the
various targets.
All the keys on the keyboard have been encoded by a specific constant,
which is part of the dictionary of this language.

Abbreviated as KyPx
EXAMPLES
1 IF KEY PRESSED ( KEY A ) THEN
2 PRINT " A has been pressed !"
3 ENDIF

545
 15 Keywords

15.278 KEY SHIFT

SYNTAX
= KEY SHIFT

PURPOSE
The KEY SHIFT function returns the current status of the various con-
trol keys. These keys such as SHIFT or ALT cannot be detected using
the standard INKEY$ or SCANCODE functions. But you can easily test
for any combination of control keys with just a single call to the KEY
SHIFT function. The result is a bit map with the following meaning:
0 -LEFT SHIFT
1 - RIGHT SHIFT
2 - CAPS LOCK
3 - CTRL
4 - LEFT ALT
’5 - RIGHT ALT
If a bit is set to a one, then the associated button has been held down
by the user.

Note that not all computers support control keys, nor is it possible to
have individual pressure detection. Depending on the target, some of
the bits may not be available, or only under certain conditions.
Alias for KEYSHIFT
Abbreviated as KySHIFT

EXAMPLES
1 CENTER " Press some control keys "
2 DO
3 LOCATE 14 , 4
4 PRINT BIN$ ( KEY SHIFT , 8)

546
 15.278 KEY SHIFT

5 LOOP

547
 15 Keywords

15.279 KEY STATE

SYNTAX
= KEY STATE(keycode)

PURPOSE
The KEY STATE command allows you to know the pressing state of a
single specific key. The reading is immediate: therefore, it is possible
to detect the pressing of even more than one key at a time and, if the
user is too fast or the program is too slow, there is the possibility that
the pressing of the key is not detected.
The parameter of this function is the so-called ”keycode”. Each key
on the target computer’s keyboard is encoded by a value, which is
specific to the hardware being considered. It should not be confused
with the ASCII code, which is a representation shared between the
various targets.
All the keys on the keyboard have been encoded by a specific constant,
which is part of the dictionary of this language.

Alias for KEYSTATE

Abbreviated as KyStt
EXAMPLES
1 IF KEY STATE ( KEY A ) THEN
2 PRINT " A has been pressed !"
3 ENDIF

548
 15.280 KEYGET

15.280 KEYGET

SYNTAX
KEYGET variable

PURPOSE
The ”KEYGET’ capture a single character typed by the user without
having to press enter. In other words, the program is ”listening” to the
keyboard and, as soon as a key is pressed, ”captures” it and stores it
in a variable given as parameter.
Unlike the INPUT command, which requires the user to press enter after
typing, KEYGET reads the character as soon as it is pressed. If no key
has been pressed, KEYGET will wait. Finally, the captured character is
stored in a string variable.

See also INKEY

Abbreviated as Kyg
EXAMPLES
1 KEYGET var$
2 PRINT var$ ;" pressed "

549
 15 Keywords

15.281 KEYSHIFT

SYNTAX
= KEYSHIFT

PURPOSE
Alias for KEY SHIFT
Abbreviated as Ks

EXAMPLES
1 CENTER " Press some control keys "
2 DO
3 LOCATE 14 , 4
4 PRINT BIN$ ( KEYSHIFT , 8)
5 LOOP

550
 15.282 KEYSTATE

15.282 KEYSTATE

SYNTAX
= KEY STATE(keycode)

PURPOSE
Alias for KEY STATE
Abbreviated as Kt

551
 15 Keywords

15.283 KILL

SYNTAX
KILL id[,id[,...]]

PURPOSE
The KILL command terminates the execution of a thread, thereby stop-
ping its execution and returning it to a ”terminated” state. This com-
mand occurs regardless of what the thread is doing; therefore, it can
cause processes or procedures to fail. Any thread can be killed at any
time, as long as it is active. If a thread is not active, killing it will have
no effect. You can interrupt a set of threads contained in an array by
supplying the array name.
Abbreviated as Ki

EXAMPLES
1 KILL handleThread

552
 15.284 LAVENDER (constant)

15.284 LAVENDER (constant)

SYNTAX
= LAVENDER

PURPOSE
This keyword represents the color lavender. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as La

EXAMPLES
1 PEN LAVENDER

553
 15 Keywords

15.285 LBOUND

SYNTAX
= LBOUND( array [, dimension])

PURPOSE
The LBOUND command (short for ”lower bound”) is used to determine
the lowest index of an array. In other words, it tells you where the count
of elements in an array begins.

Imagine an array as a cabinet with many numbered drawers. LBOUND

tells you what the number of the first drawer is. This is useful when you
need to iterate through all the elements of an array, because it gives
you the starting point of the loop.

If you have an array with multiple dimensions, you can specify the
dimension for which you want to find the lower bound:
LBOUND is essential when you write FOR loops to iterate through all the
elements of an array. It allows you to set the initial value of the loop
counter correctly.

Abbreviated as Lb
EXAMPLES
1 DIM a (10 ,20)
2 PRINT LBOUND ( a ) : REM it will print 0

554
 15.286 LCASE

15.286 LCASE

SYNTAX
= LCASE( text )

PURPOSE
Alias for LOWER
Abbreviated as Lca

EXAMPLES
1 x = LCASE ( " ugBASIC " )

555
 15 Keywords

15.287 LEFT (constant)

SYNTAX
= LEFT

PURPOSE
This constant represent the ”LEFT” key, when used as a value to com-
pare with SCANCODE,KEY STATE and KEY PRESSED. If the key does not
exist in the corresponding target, the value will be zero.

Abbreviated as Lf
EXAMPLES
1 IF KET STATE ( LEFT ) THEN
2 PRINT " LEFT has been pressed !"
3 ENDIF

556
 15.288 LEFT (function)

15.288 LEFT (function)

SYNTAX
= LEFT( text, position )

PURPOSE
The LEFT$ function lets you extract a portion of characters from a
string, starting from the beginning. In other words, it lets you ”cut” a
string from the left.

You can get prefixes, codes, or any other initial part of a string, to
combine LEFT$ with other functions to manipulate, format, and parse
strings, to use LEFT$ to check the length or initial content of a string.
The numbering of characters in a string always starts at 1. If the
specified number of characters is greater than the length of the string,
LEFT$ will return the entire string.
Make sure both string$ and substring$ are declared as strings (typically
using a $ at the end of the variable name). LEFT$ is a very useful
function for manipulating strings in BASIC, allowing you to extract
specific areas from a longer string.
See also RIGHT (function), RIGHT (instruction), MID (function),
MID (instruction), LEN
Abbreviated as Lf

EXAMPLES
1 x = LEFT ( " TEST " , 2 )

557
 15 Keywords

15.289 LEFT (instruction)

SYNTAX
= LEFT( text, position )

PURPOSE
The LEFT command replaces the leftmost characters in the destina-
tion string with the equivalent characters from the given strings. The
command has two parameters.

The first parameter is the string expression to change.

The second parameter is a numeric expression, indicating how many
characters to return. If 0, an empty string ("") is returned. On the
other hand, if greater than or equal to the number of characters in
string, the entire string is returned, untouched.
To determine the number of characters in string, you should use the
LEN function.
See also RIGHT (function), RIGHT (instruction), MID (function),
MID (instruction), LEN

Abbreviated as Lf
EXAMPLES
1 x = LEFT ( " TEST " , 2 )

558
 15.290 LEFT ALT (constant)

15.290 LEFT ALT (constant)

SYNTAX
= LEFT ALT

PURPOSE
This constant represent the left ”ALT” key, when used as bitmask for
KEY SHIFT instruction.

Alias for ALT LEFT (constant)

Abbreviated as LfAl
EXAMPLES
1 IF KEY SHIFT AND LEFT ALT THEN
2 PRINT " LEFT ALT has been pressed !"
3 ENDIF

559
 15 Keywords

15.291 LEFT ARROW (constant)

SYNTAX
= LEFT ARROW

PURPOSE
This constant represent the left arrow key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Alias for ARROW LEFT (constant)

Abbreviated as LfAw
EXAMPLES
1 IF SCANCODE = LEFT ARROW THEN
2 PRINT " LEFT ARROW has been pressed !"
3 ENDIF

560
 15.292 LEN

15.292 LEN

SYNTAX
= LEN( text )

PURPOSE
the LEN command (short for ”length”) is used to determine the length
of a string, or the total number of characters in the string. This is a
very useful command when you need to know the size of a string to
perform manipulation or comparison operations.
You can check whether a string exceeds a certain maximum length or
not. You can use LEN to create strings of a fixed length by adding
spaces or other characters. You can combine LEN with other functions
such as LEFT$, RIGHT$, and MID$ to extract and modify parts of a
string. You can compare the length of two strings to make decisions in
your program.
EXAMPLES
1 x = LEN ( " TEST " )

561
 15 Keywords

15.293 LIGHT BLUE (constant)

SYNTAX
= LIGHT BLUE

PURPOSE
This keyword represents the color light blue. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as LiBu

EXAMPLES
1 PEN LIGHT BLUE

562
 15.294 LIGHT GREEN (constant)

15.294 LIGHT GREEN (constant)

SYNTAX
= LIGHT GREEN

PURPOSE
This keyword represents the color light green. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as LiGre

EXAMPLES
1 PEN LIGHT GREEN

563
 15 Keywords

15.295 LIGHT GREY (constant)

SYNTAX
= LIGHT GREY

PURPOSE
This keyword represents the color light grey. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as LiGREY

EXAMPLES
1 PEN LIGHT GREY

564
 15.296 LIGHT RED (constant)

15.296 LIGHT RED (constant)

SYNTAX
= LIGHT RED

PURPOSE
This keyword represents the color light red. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as LiRe

EXAMPLES
1 PEN LIGHT RED

565
 15 Keywords

15.297 LINE

SYNTAX
LINE [x1], [y1] TO x2, y2[, c]
LINE TO x2, y2[, c]
LINE (x1,y1) - (x2,y2)[,mode]

PURPOSE

Alias for DRAW (instruction)

Abbreviated as Ln
EXAMPLES
1 LINE 10 ,10 TO 100 ,100 , WHITE
2 LINE TO 100 ,100

566
 15.298 LINE INPUT

15.298 LINE INPUT

SYNTAX
LINE INPUT [prompt];v1
LINE INPUT [prompt],v1

PURPOSE
The LINE INPUT command takes a complete line of text entered by
the user and assign it to a string variable. Unlike the INPUT command,
which stops at the first comma or space, LINE INPUT reads all the
characters until the user presses enter.
Typically, you precede the LINE INPUT command with a message that
tells the user what to enter. When the user presses enter, the entire
line of text typed is assigned to the variable specified after the LINE
INPUT command.
The variable containing the captured string can be used later in the
program for various operations, such as printing the value, comparing
it to other strings, or manipulating it further.

The LINE INPUT is especially useful when you want to capture sen-
tences or longer texts, which may contain spaces, commas, and other
special characters. It does not impose restrictions on the format of the
input, allowing the user to enter any type of character. It is a command
that is easy to use and understand.

See also INPUT (instruction)

Abbreviated as LnIp
EXAMPLES
1 LINE INPUT " Type a line " , a$
2 PRINT a$

567
15 Keywords

15.299 LITTLE ENDIAN (constant)

SYNTAX
= LITTLE ENDIAN

PURPOSE
The LITTLE ENDIAN is a constant that values non zero if the rappre-
sentation of data on the local CPU is in little endian. Endianness is
a concept that concerns the order in which the bytes of a multi-byte
number are stored in memory.
Imagine having an integer that spans more than one byte. Endianness
determines whether the most significant byte (the one that represents
the highest digit) is stored first (at the lowest memory address) or last.
In this case, the least significant byte is stored first. It is like reading a
book from right to left, starting with the least important word.

Endianness is a fundamental aspect of computer architecture, as it af-

fects how data is interpreted and manipulated. Different architectures
use different endianness conventions. For example: Motorola 6809 is
BIG ENDIAN, MOS 6502 is LITTLE ENDIAN.

In 8-bit computers, endianness was a crucial consideration, especially

when it came to managing integers across multiple bytes. Since these
computers had limited memory, it was essential to maximize storage
space.
With limited memory available, it was essential to use each byte effi-
ciently, and endianess directly affected arithmetic operations on multi-
byte numbers, such as addition and subtraction. Moreover, when ex-
changing data between systems with different endianness, appropriate
conversions is needed.
If you are writing code that directly manipulates memory, it is essential

568
 15.299 LITTLE ENDIAN (constant)

to know the endianness of the system to avoid data interpretation errors.

If you are developing software that needs to run on different platforms,
you need to account for endianness differences and implement data
conversion mechanisms, for data that are not manager by ugBASIC
itself.
See also BIG ENDIAN (constant)
Abbreviated as LitEnd
EXAMPLES
1 IF LITTLE ENDIAN THEN
2 PRINT " This CPU is little endian "
3 ENDIF

569
 15 Keywords

15.300 LOAD

SYNTAX
= LOAD( filename[,address] )
= LOAD( filename AS alias[,address] )

PURPOSE
The LOAD command allows you to load a generic binary file from the
file system of the host system and use it, as a buffer, directly in the
program. Loading occurs at compile time: there is no access to the
target system’s file system. If multiple uploads are made to the same
file, a single buffer will still be generated.
An absolute starting address can be given: in that case, files will be
loaded starting from that position instead of the first free position avail-
able.
Since it is possible to upload only one file of the same type at a time,
it is necessary to be able to indicate an ”alias” with which to exceed
this limit. In this regard, there is also the AS syntax, which allows you
to load the same file several times but with different names.

Abbreviated as Ld
EXAMPLES
1 testo = LOAD (" aiuto . txt ")
2 testoRipetuto = LOAD (" aiuto . txt " AS " aiuto1 ")
3 schermata = LOAD (" aiuto . txt " , 0 x8400 )
4 sc her mat a R i p e t u t a = LOAD (" aiuto . txt " AS " schermata2 " , 0 x8400 )

570
 15.301 LOAD ATLAS

15.301 LOAD ATLAS

SYNTAX
= LOAD ATLAS( filename [AS alias][,mode] ) frame [ORIGIN(dx,dy)]
[fl] [tr] [op] [bg] [bk] [READONLY]
= LOAD ATLAS( filename [AS alias][,mode] ) frame [fl] [tr]
[op] [bg] [bk] [READONLY]
frame : [ FRAME SIZE(w, h) [OFFSET(dx,dy)] [ORIGIN(zx, zy)]
| FRAME AUTO]
fl : [FLIP X] [FLIP Y] [FLIP XY] [FLIP YX]
[COMPRESSED] [OVERLAYED] [EXACT]
[ROLL X] [ROLL Y] [ROLL XY] [ROLL YX]
tr : [TRANSPARENCY | TRANSPARENCY color]
op : [OPACITY | OPACITY color]
bg : [BACKGROUND color]
bk : [UNBANKED | BANKED | BANKED(number)]

PURPOSE
The LOAD IMAGE command allows you to load an set of images and to
convert each one into an ATLAS. An Atlas is a set of images, numbered
by 0 to frame count, which can be used individually with the PUT
IMAGE command, referring to the corresponding frame. The frames
are cut out of the original image, using the size provided in the FRAME
SIZE (w, h). It should be noted that, for this reason, ATLAS images
must have a total of a size equal to an entire multiple of the size of the
individual frame. It is also possible to indicate an offset from which you
will have to start cutting the image (parameter ORIGIN(zx,zy)) and
one related to each individual cutout (OFFSET (dx, dy)).
So, the first parameter is the filename to parse. The command support
a set of modern image format, like JPEG baseline & progressive, PNG
1/2/4/8/16-bit-per-channel, TGA, BMP (non-1bpp, non-RLE), PSD

571
15 Keywords

(composited view only, no extra channels, 8/16 bit-per-channel), GIF,

HDR (radiance rgbE format), PIC (Softimage PIC) and PNM (PPM
and PGM binary only) The image will be converted into a way that can
be efficiently drawn on the screen.

The second parameter is the mode to use to convert the given data (by
default, it is equal to current mode)
Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
A series of flags, separated by spaces, can be added at loading time to
modify the behavior of ugBASIC.
The FLIP X flag allows you to flip the (entire) image horizontally, be-
fore cutting and translating it into the native format. The same is
true for the FLIP Y command, which instead inverts the (entire) image
vertically. There is also the FLIP XY (or FLIP YX) parameter to act,
simultaneously, on both directions.
The ROLL X flag allows you to SHIFT the (entire) image horizontally, for
the entire size of a frame, in order to generate intermediate frames. The
very same for ROLL Y command, which does the same vertically. There
is also the ROLL XY (or ROLL YX) parameter to act, simultaneously, on
both directions.
The COMPRESSED flag allows you to compress the image, if possible.
Compression is a space-saving mechanism, in which the native data of
the image is represented in a more compact form, which ugBASIC will
be able to quickly convert into graphics at the appropriate time.
The OVERLAYED flag can be used on systems with a palette of few
colors, to indicate which of them must be preserved during the drawing
phase, to have the transparency effect.

572
 15.301 LOAD ATLAS

The EXACT flag allows you to bypass the automatic detection of the
palette, opting for the representation of the colors according to what is
contained in it.
The (entire) image can be loaded as a transparent image (if the original
image has no transparency) using the keyword TRANSPARENCY, followe
by an optional parameter that represent the color to consider as trans-
parent.
The (entire) image can be loaded as a transparent image (if the original
image has no transparency) using the keyword OPACITY, followe by an
optional parameter that represent the color to consider as pavement,.
The resulting ATLAS can be loaded directly into the expansion memory
using the BANKED keyword. The number represent the shared resident
to use as target for this image. For some targets this is the default. If
you want, you can move the image onto the resident memory by using
the UNBANKED keyword.
Finally, if the image is not expected to change during gameplay, it can
be marked with the READONLY attribute: in this case, the image will be
stored in read-only memory, if available.
Alias for LOAD IMAGES, IMAGES LOAD, ATLAS LOAD

Abbreviated as LdAtl#
EXAMPLES
1 starship = LOAD ATLAS (" starship . png ") FRAME SIZE (16 , 16)
2 starship2 = LOAD ATLAS (" starship . png " AS " starship2 ") FRAME
SIZE (32 , 32) OFFSET (2 ,2)
3 alienAt11 = LOAD ATLAS (" alien . jpg " ,11) FRAME SIZE AUTO
4 alien2 = LOAD ATLAS (" alien . jpg " AS " alien2 " ,11) FRAME SIZE
(8 ,8) TRANSPARENCY

573
15 Keywords

15.302 LOAD IMAGE

SYNTAX
= LOAD IMAGE( filename [AS alias][,mode] ) [fl] [tr] [op]
[bg] [bk] [READONLY]
fl : [FLIP X] [FLIP Y] [FLIPXY] [FLIPYX]
[COMPRESSED] [OVERLAYED] [EXACT]
tr : [TRANSPARENCY | TRANSPARENCY color]
op : [OPACITY | OPACITY color]
bg : [BACKGROUND color]
bk : [UNBANKED | BANKED | BANKED(number)]

PURPOSE
The LOAD IMAGE command allows you to load an image and to convert
it into an IMAGE. The second parameter is the mode to use to convert
the given data (by default, it is equal to current mode)
The command support a set of modern image format, like JPEG base-
line & progressive, PNG 1/2/4/8/16-bit-per-channel, TGA, BMP (non-
1bpp, non-RLE), PSD (composited view only, no extra channels, 8/16
bit-per-channel), GIF, HDR (radiance rgbE format), PIC (Softimage
PIC) and PNM (PPM and PGM binary only) The image will be con-
verted into a way that can be efficiently drawn on the screen.
Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
A series of flags, separated by spaces, can be added at loading time to
modify the behavior of ugBASIC.
The FLIP X flag allows you to flip the image horizontally, before trans-

574
 15.302 LOAD IMAGE

lating it into the native format. The same is true for the FLIP Y com-
mand, which instead inverts the image vertically. There is also the FLIP
XY (or FLIP YX) parameter to act, simultaneously, on both directions.
The COMPRESSED flag allows you to compress the image, if possible.
Compression is a space-saving mechanism, in which the native data of
the image is represented in a more compact form, which ugBASIC will
be able to quickly convert into graphics at the appropriate time.
The OVERLAYED flag can be used on systems with a palette of few
colors, to indicate which of them must be preserved during the drawing
phase, to have the transparency effect.
The EXACT flag allows you to bypass the automatic detection of the
palette, opting for the representation of the colors according to what is
contained in it.

The image can be loaded as a transparent image (if the original image
has no transparency) using the keyword TRANSPARENCY, followe by an
optional parameter that represent the color to consider as transparent.
The image can be loaded as a transparent image (if the original image
has no transparency) using the keyword OPACITY, followe by an optional
parameter that represent the color to consider as pavement,.
The image can be loaded directly into the expansion memory using the
BANKED keyword. The number represent the shared resident to use
as target for this image. For some targets this is the default. If you
want, you can move the image onto the resident memory by using the
UNBANKED keyword.

Finally, if the image is not expected to change during gameplay, it can

be marked with the READONLY attribute: in this case, the image will be
stored in read-only memory, if available.
Alias for IMAGE LOAD

Abbreviated as LdIm

575
 15 Keywords

EXAMPLES
1 starship = LOAD IMAGE (" starship . png ")
2 starship2 = LOAD IMAGE (" starship . png " AS " starship2 ")
3 alienAt11 = LOAD IMAGE (" alien . jpg " ,11)
4 alien2 = LOAD IMAGE (" alien . jpg " AS " alien2 " ,11)

576
 15.303 LOAD IMAGES

15.303 LOAD IMAGES

SYNTAX
PURPOSE

Alias for LOAD ATLAS, ATLAS LOAD, IMAGES LOAD

Abbreviated as LdIms

577
 15 Keywords

15.304 LOAD MUSIC

SYNTAX
= LOAD MUSIC( filename )
= LOAD MUSIC( filename AS alias )

PURPOSE
The LOAD MUSIC command allows you to load a music file from the
file system of the host system and use it, as music, directly in the
program. Loading occurs at compile time: there is no access to the
target system’s file system. If multiple uploads are made to the same
file, a single buffer will still be generated.
Since it is possible to upload only one file of the same type at a time,
it is necessary to be able to indicate an ”alias” with which to exceed
this limit. In this regard, there is also the AS syntax, which allows you
to load the same file several times but with different names.
Abbreviated as LdMus
EXAMPLES
1 fugue = LOAD MUSIC (" fugue . imf ")
2 fugueAno t h e r C o p y = LOAD MUSIC (" fugue . imf " as " fugue2 ")

578
 15.305 LOAD SEQUENCE

15.305 LOAD SEQUENCE

SYNTAX
= LOAD SEQUENCE( filename [AS alias][,mode] ) frame [ORIGIN(dx,dy)]
[fl] [tr] [op] [bg] [bk] [READONLY]
= LOAD SEQUENCE( filename [AS alias][,mode] ) frame [fl] [tr]
[op] [bg] [bk] [READONLY]
frame : [ FRAME SIZE(w, h) [OFFSET(dx,dy)] [ORIGIN(zx, zy)]
| FRAME AUTO]
fl : [FLIP X] [FLIP Y] [FLIP XY] [FLIP YX]
[COMPRESSED] [OVERLAYED] [EXACT]
[ROLL X] [ROLL Y] [ROLL XY] [ROLL YX]
tr : [TRANSPARENCY | TRANSPARENCY color]
op : [OPACITY | OPACITY color]
bg : [BACKGROUND color]
bk : [UNBANKED | BANKED | BANKED(number)]

PURPOSE
The LOAD SEQUENCE command allows you to load an set of images
and to convert each one into a SEQUENCE. A Sequence is a set of set
of images, numbered by 0 to sequence count (vertically), and from
0 to frame count each (horizontally), which can be used individually
with the PUT IMAGE command, referring to the corresponding frame
and sequence. The frames are cut out of the original image, using the
size provided in the FRAME SIZE (w, h). It should be noted that, for
this reason, SEQUENCE images must have a total of a size equal to an
entire multiple of the size of the individual frame. It is also possible to
indicate an offset from which you will have to start cutting the image
(parameter ORIGIN(zx,zy)) and one related to each individual cutout
(OFFSET (dx, dy)).
So, the first parameter is the filename to parse. The command support

579
15 Keywords

a set of modern image format, like JPEG baseline & progressive, PNG
1/2/4/8/16-bit-per-channel, TGA, BMP (non-1bpp, non-RLE), PSD
(composited view only, no extra channels, 8/16 bit-per-channel), GIF,
HDR (radiance rgbE format), PIC (Softimage PIC) and PNM (PPM
and PGM binary only) The image will be converted into a way that can
be efficiently drawn on the screen.
The second parameter is the mode to use to convert the given data (by
default, it is equal to current mode)
Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
A series of flags, separated by spaces, can be added at loading time to
modify the behavior of ugBASIC.

The FLIP X flag allows you to flip the (entire) image horizontally, be-
fore cutting and translating it into the native format. The same is
true for the FLIP Y command, which instead inverts the (entire) image
vertically. There is also the FLIP XY (or FLIP YX) parameter to act,
simultaneously, on both directions.

The ROLL X flag allows you to SHIFT the (entire) image horizontally, for
the entire size of a frame, in order to generate intermediate frames. The
very same for ROLL Y command, which does the same vertically. There
is also the ROLL XY (or ROLL YX) parameter to act, simultaneously, on
both directions.

The COMPRESSED flag allows you to compress the image, if possible.

Compression is a space-saving mechanism, in which the native data of
the image is represented in a more compact form, which ugBASIC will
be able to quickly convert into graphics at the appropriate time.
The OVERLAYED flag can be used on systems with a palette of few
colors, to indicate which of them must be preserved during the drawing

580
 15.305 LOAD SEQUENCE

phase, to have the transparency effect.

The EXACT flag allows you to bypass the automatic detection of the
palette, opting for the representation of the colors according to what is
contained in it.

The (entire) image can be loaded as a transparent image (if the original
image has no transparency) using the keyword TRANSPARENCY, followe
by an optional parameter that represent the color to consider as trans-
parent.

The (entire) image can be loaded as a transparent image (if the original
image has no transparency) using the keyword OPACITY, followe by an
optional parameter that represent the color to consider as pavement,.
The resulting SEQUENCE can be loaded directly into the expansion mem-
ory using the BANKED keyword. The number represent the shared resi-
dent to use as target for this image. For some targets this is the default.
If you want, you can move the image onto the resident memory by using
the UNBANKED keyword.
Finally, if the image is not expected to change during gameplay, it can
be marked with the READONLY attribute: in this case, the image will be
stored in read-only memory, if available.
Alias for STRIP LOAD
Abbreviated as LdSeq
EXAMPLES
1 starship = LOAD SEQUENCE (" starship . png ") FRAME SIZE (16 , 16)
2 starship2 = LOAD SEQUENCE (" starship . png " AS " starship2 ") FRAME
SIZE (32 , 32) OFFSET (2 ,2)
3 alienAt11 = LOAD SEQUENCE (" alien . jpg " ,11) FRAME SIZE AUTO
4 alien2 = LOAD SEQUENCE (" alien . jpg " AS " alien2 " ,11) FRAME SIZE
(8 ,8) TRANSPARENCY

581
15 Keywords

15.306 LOAD TILE

SYNTAX
= LOAD TILE( filename [AS alias][,mode] ) [fl]
fl : [FLIP X] [FLIP Y] [FLIP XY] [FLIP YX]
fl : [ROLL X] [ROLL Y] [ROLL XY] [ROLL YX]

PURPOSE
The LOAD TILE command allows you to load an image and to convert
it into an TILE, that is a format that will be converted into a way
that can be efficiently drawn on the screen using the tiles. The second
parameter is the mode to use to convert the given data (by default, it
is equal to current mode)
The command support a set of modern image format, like JPEG base-
line & progressive, PNG 1/2/4/8/16-bit-per-channel, TGA, BMP (non-
1bpp, non-RLE), PSD (composited view only, no extra channels, 8/16
bit-per-channel), GIF, HDR (radiance rgbE format), PIC (Softimage
PIC) and PNM (PPM and PGM binary only) The image will be con-
verted into a way that can be efficiently drawn on the screen.

Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
A series of flags, separated by spaces, can be added at loading time to
modify the behavior of ugBASIC.
The FLIP X flag allows you to flip the image horizontally, before trans-
lating it into the native format. The same is true for the FLIP Y com-
mand, which instead inverts the image vertically. There is also the FLIP
XY (or FLIP YX) parameter to act, simultaneously, on both directions.

582
 15.306 LOAD TILE

The COMPRESSED flag allows you to compress the image, if possible.

Compression is a space-saving mechanism, in which the native data of
the image is represented in a more compact form, which ugBASIC will
be able to quickly convert into graphics at the appropriate time.

The ROLL X flag allows you to SHIFT the (entire) image horizontally, for
the entire size of a frame, in order to generate intermediate frames. The
very same for ROLL Y command, which does the same vertically. There
is also the ROLL XY (or ROLL YX) parameter to act, simultaneously, on
both directions.

Alias for TILE LOAD

Abbreviated as LdTl
EXAMPLES
1 starship = LOAD TILE (" starship . png ")
2 starship2 = LOAD TILE (" starship . png " AS " starship2 ")
3 alienAt11 = LOAD TILE (" alien . jpg " ,11)
4 alien2 = LOAD TILE (" alien . jpg " AS " alien2 " ,11)

583
 15 Keywords

15.307 LOAD TILEMAP

SYNTAX
= LOAD TILEMAP(filename)

PURPOSE
The LOAD TILEMAP command allow to load a TILEMAP datatype that
will represent a map of those drawn by means of Tiled.

Abbreviated as LdTm
EXAMPLES
1 x = LOAD TILEMAP (" dungeon . tmx ")

584
 15.308 LOAD TILES

15.308 LOAD TILES

SYNTAX
= LOAD TILE( filename [AS alias][,mode] ) [fl]
fl : [FLIP X] [FLIP Y] [FLIP XY] [FLIP YX]
fl : [ROLL X] [ROLL Y] [ROLL XY] [ROLL YX]

PURPOSE
The LOAD TILES command allows you to load an image and to convert
it into multiple TILE, that is a format that will be converted into a way
that can be efficiently drawn on the screen using the tiles. The second
parameter is the mode to use to convert the given data (by default, it
is equal to current mode)
The command support a set of modern image format, like JPEG base-
line & progressive, PNG 1/2/4/8/16-bit-per-channel, TGA, BMP (non-
1bpp, non-RLE), PSD (composited view only, no extra channels, 8/16
bit-per-channel), GIF, HDR (radiance rgbE format), PIC (Softimage
PIC) and PNM (PPM and PGM binary only) The image will be con-
verted into a way that can be efficiently drawn on the screen.

Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
A series of flags, separated by spaces, can be added at loading time to
modify the behavior of ugBASIC.
The FLIP X flag allows you to flip the image horizontally, before trans-
lating it into the native format. The same is true for the FLIP Y com-
mand, which instead inverts the image vertically. There is also the FLIP
XY (or FLIP YX) parameter to act, simultaneously, on both directions.

585
 15 Keywords

The COMPRESSED flag allows you to compress the image, if possible.

Compression is a space-saving mechanism, in which the native data of
the image is represented in a more compact form, which ugBASIC will
be able to quickly convert into graphics at the appropriate time.

The ROLL X flag allows you to SHIFT the (entire) image horizontally, for
the entire size of a frame, in order to generate intermediate frames. The
very same for ROLL Y command, which does the same vertically. There
is also the ROLL XY (or ROLL YX) parameter to act, simultaneously, on
both directions.

Alias for TILES LOAD, FONT LOAD

Abbreviated as LdTls
EXAMPLES
1 starship = LOAD TILES (" starship . png ")
2 starship2 = LOAD TILES (" starship . png " AS " starship2 ")
3 alienAt11 = LOAD TILES (" alien . jpg " ,11)
4 alien2 = LOAD TILES (" alien . jpg " AS " alien2 " ,11)

586
 15.309 LOAD TILESET

15.309 LOAD TILESET

SYNTAX
= LOAD TILESET( filename )
= LOAD TILESET( filename AS alias )

PURPOSE
The LOAD TILESET command allows you to load a tileset with the
”Tiled TSX” file format. Offset and other parameters will be calculated
automatically on the base of the file content.
The image will be converted into a way that can be efficiently drawn
on the screen. It could be converted into indexed palette, and can be
rescaled as well.

Since it is possible to load only one file of the same type at a time, it
is necessary to be able to indicate an ”alias” with which to exceed this
limit. In this regard, there is also the AS syntax, which allows you to
load the same file several times but with different names.
Abbreviated as LdTse

EXAMPLES
1 x = LOAD TILESET (" dungeon . tsx ")
2 x = LOAD TILESET (" dungeon . tsx " AS " dungeon ")

587
15 Keywords

15.310 LOCATE

SYNTAX
LOCATE [x],[y]

PURPOSE
The LOCATE command moves the text cursor to specific coordinates,
and this new location sets the start position for all subsequent text
printing until commanded otherwise.

All console positions are measured in “text coordinates”, which are mea-
sured in units of one printed character on console, with the x-coordinate
controlling the horizontal position and the y-coordinate referring to the
vertical.
The top left-hand corner of the console has coordinates of 0,0 whereas
text coordinates of 15,10 refer to a position 15 characters from the
left-hand edge of the console and 10 characters from the top.
The range of these coordinates will depend on the size of your char-
acter set and the dimensions of the display area allocated, known as a
“console”.

All coordinate measurements are taken using text coordinates relative

to the current console. If you try and print something outside of these
console,the console will be automatically scrolled down.
The current console is automatically treated as a window, so there is
no need to ”open” one.

See also AT$, CMOVE

Abbreviated as Lc
EXAMPLES

588
 15.310 LOCATE

1 LOCATE 15 ,0
2 LOCATE ,20

589
 15 Keywords

15.311 LOCATE (function)

SYNTAX
= LOCATE$( x , y )
= LOCATE( x , y )

PURPOSE
See also AT (function)

Abbreviated as Lc
EXAMPLES
1 PRINT LOCATE$ (10 ,10) ; " at 10 , 10"

590
 15.312 LOG

15.312 LOG

SYNTAX
= LOG(number)

PURPOSE
The LOG instruction calculate the natural logarithm of the given number,
that must be FLOAT. This is a mathematical function that is the inverse
of the natural exponential (with base e). In other words, the natural
logarithm of a number x is the exponent to which Napier’s number (e
= 2.71828) must be raised to obtain x.
This function can be used to solve differential equations, calculate in-
tegrals and approximate functions, for normalizing data and it is used
in many physical and biological models.

Abbreviated as Lg
EXAMPLES
1 x = LOG (21)

591
 15 Keywords

15.313 LOGIN

SYNTAX
= LOGIN( username, password )

PURPOSE
The LOGIN function will allow to connect with a DOJO server. On
DOJO servers there is no different process between registration and
access to the systems: this is because, in fact, it is unlikely that the
user’s situation has persisted on the retrocomputers. It follows that, at
the first attempt to access, there will also be contextual registration of
the user; after the first access, each subsequent access must have the
same credentials, and there is no way to change them, at least with
actual version of the DOJO protocol.

The LOGIN function return a sessionId, to be used on other commands

/ functions. To verify that the operation has taken place, the SUCCESS()
function must be used. If SUCCESS(...) returns a TRUE result, then
the login process was successful; if it returns a FALSE result, then the
process must be considered failed for some reason (the username may
have already been used, or the credentials are incorrect, and so on).
Alias for DOJO LOGIN
Abbreviated as Lgn
AVAILABLE ON

c64 c64reu coco coco3

EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )

592
 15.314 LONG (data type)

15.314 LONG (data type)

SYNTAX
... AS LONG

PURPOSE
The LONG is a data type that allow to store a signed 32-bit word.
Alias for SIGNED DWORD (data type)

Abbreviated as Lo
EXAMPLES
1 DIM parolaLunga AS LONG

593
 15 Keywords

15.315 LOOP...END LOOP

SYNTAX
LOOP
... instructions ...
END LOOP

PURPOSE

Alias for DO...LOOP

Abbreviated as LpEeLp
EXAMPLES
1 LOOP
2 x = x + 1
3 END LOOP

594
 15.316 LOWER

15.316 LOWER

SYNTAX
= LOWER( text )

PURPOSE
The LOWER function converts all uppercase characters in a string to
lowercase. In other words, it takes a string as input and returns a new
string that is identical to the first, but with all the letters lowercase.

The LOWER function examines each character in the input string. If

the character is an uppercase letter, it is converted to its lowercase
equivalent. All other characters (numbers, symbols, spaces) remain
unchanged.

Before comparing or searching strings, it is often useful to convert all

strings to lowercase or uppercase to avoid case-sensitive problems. It
can be used to make user input less case-sensitive, such as to check
whether a keyword was entered correctly regardless of case. To perform
search and replace, text parsing, and other string manipulation, the
LOWER command is ideal.

Alias for LCASE

Abbreviated as Lw
EXAMPLES
1 x = LOWER ( " ugBASIC " )

595
 15 Keywords

15.317 MAGENTA (constant)

SYNTAX
= MAGENTA

PURPOSE
This keyword represents the color magenta. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as Mg

EXAMPLES
1 PEN MAGENTA

596
 15.318 MAX

15.318 MAX

SYNTAX
= MAX(#const1,#const2)
= MAX(val1,val2)
= MAX(string1,string2)

PURPOSE

The MAX function allows you to identify the greater of two values. If
both terms are (numeric) constants, the evaluation is carried out at the
time of compilation. Otherwise, the value is calculated at runtime.
Where the data types are not identical, ugBASIC ”promotes” the second
term to the type of the first term. If the conversion is not possible, a
specific error will be issued. The comparison of heterogeneous types
is, in effect, a comparison of implicitly promoted types. In particular,
static strings are always promoted to dynamic strings.
Abbreviated as Mx
EXAMPLES
1 result = MAX ( a , b )

597
 15 Keywords

15.319 MEMORIZE

SYNTAX
MEMORIZE

PURPOSE
The MEMORIZE command allows you to store the current position of the
cursor, in terms of coordinates, relative to the current console. The
cursor coordinates can be restored with the REMEMBER command. Note
that the two commands operate on the current console. If there are
no consoles defined, using this method implicitly defines CONSOLE 0 as
the entire screen.
See also REMEMBER

Abbreviated as Me
EXAMPLES
1 MEMORIZE

598
 15.320 MID (function)

15.320 MID (function)

SYNTAX
= MID( text, position )

PURPOSE
The MID function returns a (dynamic) string containing a specified num-
ber of characters from a string. It has three parameters.

The first parameter is the string expression from which characters are
returned. If string is empty, an empty string is returned.
The second parameter is the character position in string at which the
part to be taken begins. If start is greater than the number of characters
in string, MID returns a zero-length string (””).

The third parameter is optional, and gives the number of characters to

return. If omitted or if there are fewer than length characters in the text
(including the character at start), all characters from the start position
to the end of the string are returned.
See also LEFT (function), LEFT (instruction), MID (instruction),
RIGHT (function), RIGHT (instruction), LEN
Abbreviated as Mi
EXAMPLES
1 x = MID ( " TEST " , 2 )

599
 15 Keywords

15.321 MID (instruction)

SYNTAX
MID( string, pos[, len] ) = value

PURPOSE
The MID statement allows to change a (dynamic) string containing a
specified number of characters from a string. It has three parameters.

The first parameter is the string expression to modify.

The second parameter is the character position in string at which the
part to be taken begins. If start is greater than the number of characters
in string, MID replace at the end of the string.
The third parameter is optional, and gives the number of characters
to replace. If omitted or if there are fewer than length characters in
the text (including the character at start), all characters from the start
position to the end of the string are replaced.
See also LEFT (function), LEFT (instruction), MID (function),
RIGHT (function), RIGHT (instruction), LEN

Abbreviated as Mi
EXAMPLES
1 a$ = " PUNTO ": MID ( a$ , 1 , 3 ) = " PON ": PRINT a$ : REM prints "
PONTO "

600
 15.322 MIN

15.322 MIN

SYNTAX
= MIN(#const1,#const2)
= MIN(val1,val2)
= MIN(string1,string2)

PURPOSE

The MIN function allows you to identify the smaller of two values. If
both terms are (numeric) constants, the evaluation is carried out at the
time of compilation. Otherwise, the value is calculated at runtime.
Where the data types are not identical, ugBASIC ”promotes” the second
term to the type of the first term. If the conversion is not possible, a
specific error will be issued. The comparison of heterogeneous types
is, in effect, a comparison of implicitly promoted types. In particular,
static strings are always promoted to dynamic strings.
Abbreviated as Mn
EXAMPLES
1 result = MIN ( a , b )

601
 15 Keywords

15.323 MINUS (constant)

SYNTAX
= MINUS

PURPOSE
This constant represent the ”MINUS” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Min
EXAMPLES
1 IF KET STATE ( MINUS ) THEN
2 PRINT " MINUS has been pressed !"
3 ENDIF

602
 15.324 MMOVE

15.324 MMOVE

SYNTAX
MMOVE [MEMORY] address1 TO [MEMORY] address2 SIZE size
MMOVE [MEMORY] address1 TO VIDEO address2 SIZE size
MMOVE VIDEO address1 TO [MEMORY] address2 SIZE size

PURPOSE

This command moves a block of memory of size bytes between two

memory locations. In particular, it is possible to indicate whether the
destination or source of the movement is the computer’s resident mem-
ory or the memory dedicated to the video card, which on some targets
is separate from the main memory.
Abbreviated as Mmv

EXAMPLES
1 MMOVE MEMORY & Hc000 TO VIDEO & H8000 SIZE 100

603
15 Keywords

15.325 MOB OFF

SYNTAX
MOB OFF

PURPOSE
Alias for SPRITE DISABLE
Abbreviated as MbOf

604
 15.326 MOB ON

15.326 MOB ON

SYNTAX
MOB ON

PURPOSE
Alias for SPRITE ENABLE
Abbreviated as MbON

605
 15 Keywords

15.327 MOD

SYNTAX
= x MOD y

PURPOSE
The MOD operator is used to perform the modulo operation. This op-
eration returns the remainder of the integer division of two numbers.
The result of a MOD operation will not retain the sign of any, and so it
may be only positive. The result is always in the range [0, divisor),
exclusive.
If the result of MOD is 0, it means that the first number is divisible by
the second. Often used in conjunction with a pseudo-random number
generator to obtain random numbers within a certain range. It can be
used to create loops that repeat a certain number of times or to handle
situations that repeat periodically.

For example:
8 Mod 3 = 2
-8 Mod 3 = 2
8 Mod -3 = 2
-8 Mod -3 = 2

If divisor evaluates to zero, the behavior of the MOD operator is to return

the dividend as result, without sign.
Abbreviated as M%

EXAMPLES
1 IF x MOD 2 THEN
2 PRINT " odd "
3 ELSE

606
 15.327 MOD

4 PRINT " even "

5 ENDIF

607
 15 Keywords

15.328 MSPRITE (data type)

SYNTAX
... AS MSPRITE

PURPOSE
The MSPRITE is a data type that allow to store a reference to a multi-
plexed sprite.

Abbreviated as Msp
EXAMPLES
1 DIM player AS MSPRITE

608
 15.329 MSPRITE (function)

15.329 MSPRITE (function)

SYNTAX
= MSPRITE ( name flags )
= MSPRITE ( name, previous flags )

PURPOSE
This statement allows you to define a multiplexed sprite. These objects
are managed entirely by ugBASIC, and using SPRITE as usual. A mul-
tiplexed sprite is a composition of composite sprite where each element
of the composition is done by using a virtual sprite that, in turns, use
a real (hardware) sprite.
sprites where images are cropped, the size of a multiplexed sprite is
taken directly from the image data, and it is rounded to the underly-
ing hardware size (so a 32x32 monochromatic image as above will be
converted into 4 hardware sprites of 24x21 pixels). So, if the hard-
ware sprites cannot be resized, a part of the area inside these sprites
is wasted, and that you need more than one sprite to represent a large
image.

The maximum of eight hardware sprites therefore imposes a strict limit

to the number of such objects you can display on a horizontal line.
The total width of the objects must not exceed: 24*8=192 pixels (for
monochrome sprites) 16*4=96 pixels (for two colors sprites) 16*2=48
pixels (for four colors sprites) 16*1=24 pixels (for eight colors sprites)

If you try to ignore this limitation, you won’t get an error message, but
your multiplexed sprite will not be displayed on the screen. So it’s vital
to ensure that the above restriction is respected.
The function accepts the name of a graphic resource, among those
previously loaded. This must correspond to a single image: therefore it

609
15 Keywords

can be an image or a frame of an ATLAS or a SEQUENCE. The system,

in a completely automatic way, will convert the resource into graphic
data compatible with the sprite format.
The command accepts a series of parameters, which can be added after
the name of the graphic resource. The EXPAND VERTICAL parameter
allows you to double the vertical dimensions, making each pixel oc-
cupy two or more vertical pixels. On the other hand, the COMPRESS
VERTICAL command allows you to restore the original dimensions. The
EXPAND HORIZONTAL parameter allows you to double the vertical di-
mensions, making each pixel occupy two or more vertical pixels. On
the other hand, the COMPRESS HORIZONTAL command allows you to
restore the original dimensions. Finally, it is possible to indicate one of
the colors in the palette as ”transparent”, and therefore that it does
not need to generate a hardware sprite. This can be useful where the
graphic resource does not use the color black, which is the standard
color to characterize the background. Due to the isomorphic nature of
the language, not all flags are usable, or have an effect, on all targets
that support sprites.
The function provides additional syntax, valid for redefining a sprite
already defined. The purpose of such syntax is to modify the graphic
information inherent to a sprite already defined previously, thus being
able to dynamically replace the appearance of the sprite. In this case,
it is necessary to provide a reference to the previously defined sprite
(previous), and ensure that the graphic characteristics (such as the
number of colors) are identical.

See also CSPRITE, SPRITE

Abbreviated as Msp
AVAILABLE ON
c128 c64 c64reu

EXAMPLES

610
 15.329 MSPRITE (function)

1 spaceshift = MSPRITE ( LOAD IMAGE ( " spaceship . png " ) IGNORE

COLOR GREEN )
2 alien = MSPRITE ( LOAD IMAGE ( " alien1 . png " ) )
3 alien = MSPRITE ( LOAD IMAGE ( " alien2 . png " ) , alien )

611
15 Keywords

15.330 MSPRITE UPDATE

SYNTAX
PURPOSE

This instruction causes multiplexed sprites to be updated, where an

asynchronous update has been requested.
Abbreviated as MspUpd
AVAILABLE ON

c128 c64 c64reu

612
 15.331 MUL

15.331 MUL

SYNTAX
MUL var, expr

PURPOSE
The MUL statement is used to multiply the value of a numeric variable
by a specified amount. In other words, it is like multiply one number
with another. It is the same as var = var * expr.

It takes the var to which you want to multiply a value and the expr
as the expression you want to multiply to the variable.
Abbreviated as Mu

EXAMPLES
1 MUL v , 42

613
 15 Keywords

15.332 MULTI

SYNTAX
MULTI color1, color2, color3

PURPOSE
MULTI sets three of the colors of the C64’s multicolor mode and
switches the multicolor mode on. The fourth possible color (the back-
ground color, multicolor bit combination %00, controlled by memory
address $D021) is defined with the COLOR command. The first pa-
rameter of MULTI (color1) controls the color of the bit combination
%01, color2 corresponds to the color of the bit combination %10 and
color3 colors the bit combination %11.
See also MULTI ON, MULTI OFF

Abbreviated as Mlt
EXAMPLES
1 MULTI RED , GREEN , YELLOW

614
 15.333 MULTI OFF

15.333 MULTI OFF

SYNTAX
MULTI OFF

PURPOSE
MULTI OFF deactivates the multicolor mode.
See also MULTI ON

Abbreviated as MltOf
EXAMPLES
1 MULTI OFF

615
 15 Keywords

15.334 MULTI ON

SYNTAX
MULTI ON

PURPOSE
MULTI ON activates the multicolor mode without setting any colors.
See also MULTI OFF

Abbreviated as MltON
EXAMPLES
1 MULTI ON

616
 15.335 MUSIC

15.335 MUSIC

SYNTAX
MUSIC [LOOP] music [format]
MUSIC music [format] [LOOP]

PURPOSE
The MUSIC command starts a piece of music from the music variable.
This music will be played independently of your program, without af-
fecting it in the slightest.
Normally, it’s possible to store several complete arrangements. Each
composition is assigned its own individual music variable.
The music system is intelligent, and will automatically suspend your
music for the duration of any subsequent sound effects on the current
channel. When the sound has finished, your tune will be restarted from
its previous position.
The command accepts an additional keyword, LOOP, which allows you
to indicate that the piece of music must be played without ever ending
playback: ugBASIC will make it start again from the beginning, once
playback has finished.
Finally, the command accepts the indication of the format in which
the music is stored in the variable. This specification is necessary only
if the audio file was not loaded by the LOAD MUSIC command. The
LOAD MUSIC command takes care of converting one of the supported
formats into the internal (IAF) ugBASIC format. However, ugBASIC
can play formats compatible with your audio hardware. In this case,
by specifying the format in which the data is prepared, it is possible to
follow up on this request.
Each target has a specific list of supported audio formats.

617
 15 Keywords

Abbreviated as Mus
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc msx1 pc128op plus4
sc3000 sg1000 to8 vic20
EXAMPLES
1 MUSIC fugue
2 MUSIC backmusic LOOP
3 MUSIC soundtrack PSG

618
 15.336 MUSIC (data type)

15.336 MUSIC (data type)

SYNTAX
... AS MUSIC

PURPOSE
The MUSIC is a data type that reference the data for any music track.
Abbreviated as Mus

EXAMPLES
1 DIM music AS MUSIC

619
 15 Keywords

15.337 MUSIC (storage)

SYNTAX
MUSIC source AS target

PURPOSE
The MUSIC command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
a music. The basic syntax requires indicating the name of the source
file that will be converted and inserted into the medium. If you don’t
want to use the same name, you can indicate an alias (AS target).
Abbreviated as Mus
EXAMPLES
1 MUSIC " fugue . mid " AS " fugue "

620
 15.338 MUSIC PAUSE

15.338 MUSIC PAUSE

SYNTAX
MUSIC PAUSE

PURPOSE
The MUSIC PAUSE command allows you to temporarily suspend the
performance of a piece of music. The suspension is carried out either
by interrupting the execution of the notes and by setting the volume to
zero. The music can be reactivated using the command MUSIC RESUME.
Abbreviated as MusPau
AVAILABLE ON

atari c128 c128z c64 coco coco3 coleco cpc msx1 pc128op plus4
sc3000 sg1000 to8 vic20
EXAMPLES
1 MUSIC PAUSE : WAIT KEY : MUSIC RESUME

621
 15 Keywords

15.339 MUSIC RESUME

SYNTAX
MUSIC RESUME

PURPOSE
The MUSIC RESUME command allows you to resume a suspended per-
formance of a piece of music. The music can be suspended using the
command MUSIC PAUSE.

Abbreviated as MusRsm
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc msx1 pc128op plus4
sc3000 sg1000 to8 vic20

EXAMPLES
1 MUSIC PAUSE : WAIT KEY : MUSIC RESUME

622
 15.340 MUSIC SEEK

15.340 MUSIC SEEK

SYNTAX
MUSIC SEEK position

PURPOSE
The MUSIC SEEK command allows you to move the reproduction to a
specific position.

Abbreviated as Mussk
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc msx1 pc128op plus4
sc3000 sg1000 to8 vic20

EXAMPLES
1 MUSIC SEEK 42

623
 15 Keywords

15.341 MUSIC STOP

SYNTAX
MUSIC STOP

PURPOSE
The MUSIC STOP command allows you to halt definitively the perfor-
mance of a piece of music.

Abbreviated as MusSt
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc msx1 pc128op plus4
sc3000 sg1000 to8 vic20

EXAMPLES
1 MUSIC STOP

624
 15.342 NEW ATLAS

15.342 NEW ATLAS

SYNTAX
= NEW ATLAS( frames, width, height )

PURPOSE
The NEW ATLAS command allows you to define a memory area where
you can store a set of images coming from the screen (with the GET
IMAGE command), or from another graphic resource.

The area must be defined by (constant) number of frames, (constant)

width and (constant) height, expressed in pixels. The actual size, in
terms of bytes of RAM, will depend on the graphics mode selected at
the time.

If it is not possible to define an image in that screen mode, a specific

error will be issued.
Alias for NEW IMAGES
Abbreviated as NwAtl#

EXAMPLES
1 background = NEW ATLAS (16 , 32 ,32)

625
 15 Keywords

15.343 NEW IMAGE

SYNTAX
= NEW IMAGE( width, height )

PURPOSE
The NEW IMAGE command allows you to define a memory area where
you can store an image coming from the screen (with the GET IMAGE
command), or from another graphic resource.

The area must be defined by (constant) width and (constant) height,

expressed in pixels. The actual size, in terms of bytes of RAM, will
depend on the graphics mode selected at the time.
If it is not possible to define an image in that screen mode, a specific
error will be issued.
Abbreviated as NwIm
EXAMPLES
1 background = NEW IMAGE (32 ,32)

626
 15.344 NEW IMAGES

15.344 NEW IMAGES

SYNTAX
PURPOSE

Alias for NEW ATLAS

Abbreviated as NwIms

627
 15 Keywords

15.345 NEW MUSIC

SYNTAX
= NEW MUSIC( size )

PURPOSE
The NEW MUSIC command allows you to define a memory area where
you can store a set of notes for a MUSIC.

Abbreviated as NwMus
EXAMPLES
1 track = NEW MUSIC (1260)

628
 15.346 NEW SEQUENCE

15.346 NEW SEQUENCE

SYNTAX
= NEW SEQUENCE( strips, frames, width, height )

PURPOSE
The NEW SEQUENCE command allows you to define a memory area where
you can store a set of images coming from the screen (with the GET
IMAGE command), or from another graphic resource.

The area must be defined by (constant) number of strips, (constant)

frames, (constant) width and (constant) height, expressed in pixels.
The actual size, in terms of bytes of RAM, will depend on the graphics
mode selected at the time.

If it is not possible to define an image in that screen mode, a specific

error will be issued.
Alias for NEW IMAGES
Abbreviated as NwSeq

EXAMPLES
1 background = NEW SEQUENCE (2 , 16 , 32 ,32)

629
 15 Keywords

15.347 NEXT RASTER

SYNTAX
NEXT RASTER

PURPOSE
The NEXT RASTER instruction will resume execution of the main pro-
gram from where it had stopped, before serving the interrupt for the
raster.

Wait for the next raster. Meanwhile, the execution of the main code
will resume where it left off.
See also NEXT RASTER AT, RASTER AT

Abbreviated as NxRst
AVAILABLE ON
c128 c64 c64reu plus4
EXAMPLES
1 NEXT RASTER

630
 15.348 NEXT RASTER AT

15.348 NEXT RASTER AT

SYNTAX
NEXT RASTER AT line WITH label
NEXT RASTER label AT line

PURPOSE
The NEXT RASTER AT instruction will resume execution of the main
program from where it had stopped, before serving the interrupt for the
raster, and will set the next raster line where the main program will be
interrupted.
See also NEXT RASTER, RASTER AT
Abbreviated as NxRstAt

AVAILABLE ON
c128 c64 plus4
EXAMPLES
1 NEXT RASTER AT #& H42 WITH my R as te rR o ut in e

631
 15 Keywords

15.349 NONE (constant)

SYNTAX
= NONE

PURPOSE
This constant represent the fact that no key has been pressed, when
used as a valueto compare with SCANCODE.

Abbreviated as Nn
EXAMPLES
1 IF SCANCODE = NONE THEN
2 PRINT " No key has been pressed "
3 ENDIF

632
 15.350 NOP

15.350 NOP

SYNTAX
NOP

PURPOSE
NOP is short for ”No OPeration” and it is a very special instruction: it
generates an equivalent instruction in assembly languages that does not
perform any useful operation, that is, it does not change the state of
the processor or the data in memory.
By inserting a sequence of NOP instructions, you can create a timed delay
within your program. This can be useful, for example, to synchronize
several actions or to create animation effects. In some cases, it is
necessary to align the code to certain memory locations. By inserting
NOP instructions, you can ”fill” the missing space and ensure correct
alignment. NOP instructions can be used to insert ”placeholders” into
code, making debugging and testing easier.
When the program encounters a NOP instruction, it simply increments
the program counter (PC) to the next instruction, without performing
any data operations. In effect, the processor ”wastes time” executing
this empty instruction.
It is important to note that excessive use of NOP instructions can slow
down the execution of the program, so it is advisable to use them
sparingly and only when absolutely necessary.

Abbreviated as Np
EXAMPLES
1 IF tooEarly THEN
2 NOP : NOP : NOP : NOP : NOP
3 ENDIF

633
15 Keywords

15.351 NOT

SYNTAX
= NOT x

PURPOSE
Performs a logical negation on an expression, as a bitwise negation. For
comparisons managed as a boolean result (TRUE or FALSE), result is
TRUE if expresions evaluate as FALSE. The following table shows how
result is determined:
NOT TRUE = FALSE
NOT FALSE = TRUE

Generally speaking, the NOT operator performs a bitwise negation of the

bits of the expression and sets the corresponding bit in result according
to the previous table.
Note that ugBASIC uses the convention, very common in BASICs of the
1970s and 1980s, of considering Boolean logic as implemented through
the so-called ”two’s complement”.

In other words, the value FALSE is associated with a number composed

of all 0s, in terms of bits. The value TRUE is, instead, associated with a
number composed of all 1s, again in terms of bits. According to the 2’s
complement representation, a number composed of all ones is always
equivalent to the number -1, regardless of how many bits the number is
composed of, while a number composed of all zeros is always equivalent
to zero.
According to this convention, there is a coincidence between bitwise
and logical operations: in fact, a bitwise NOT, applied to all the bits of
the number, will be equivalent to the logical operation.

634
 15.351 NOT

Because the logical and bitwise operators have lower precedence than
other arithmetic and relational operators, all bitwise operations must be
enclosed in parentheses to ensure accurate results.
Abbreviated as Nt

EXAMPLES
1 IF NOT x THEN
2 PRINT " x is FALSE "
3 ELSE
4 PRINT " x is TRUE "
5 ENDIF

635
 15 Keywords

15.352 NOTE (constant)

SYNTAX
NOTE note [#] [octave]
note: C|D|E|F|G|A|B

PURPOSE
The keyword NOTE allows you to indicate a note on the musical scale.
The syntax must indicate the note, any variations and the reference
octave. If the octave is omitted, octave no. 4 (the fifth octave) is
understood.
Abbreviated as Ne
EXAMPLES
1 SOUND NOTE C #3 , 200

636
 15.353 NRM

15.353 NRM

SYNTAX
NRM

PURPOSE
NRM resets the chipset to its default values: the graphic mode is switched
off, uppercase and lowercase font is activated, the extended color mode
is switched off.

Abbreviated as Nr
EXAMPLES
1 NRM

637
 15 Keywords

15.354 NTSC (constant)

SYNTAX
= NTSC

PURPOSE
The keyword NTSC allows you to know if the target is running with a
video chipset that supports NTSC standard.

Abbreviated as Nts
EXAMPLES
1 IF NTSC THEN
2 PRINT " I am using the NTSC video standard !"
3 ENDIF

638
 15.355 OLIVE GREEN (constant)

15.355 OLIVE GREEN (constant)

SYNTAX
= OLIVE GREEN

PURPOSE
This keyword represents the color olive green. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as OlGre

EXAMPLES
1 PEN OLIVE GREEN

639
 15 Keywords

15.356 ON SCROLL...CALL

SYNTAX
ON SCROLL UP ROW CALL label
ON SCROLL DOWN ROW CALL label
ON SCROLL LEFT COLUMN CALL label
ON SCROLL RIGHT COLUMN CALL label

PURPOSE

This command is used to force a procedure call when the screen is

scrolled down by an entire row or column.
Important: this command does not follow the OPTION CALL AS GOTO
pragma.

Abbreviated as ONSclCa
EXAMPLES
1 ON SCROLL UP ROW CALL scrolledAway

640
 15.357 ON SCROLL...GOSUB

15.357 ON SCROLL...GOSUB

SYNTAX
ON SCROLL UP ROW GOSUB label
ON SCROLL DOWN ROW GOSUB label
ON SCROLL LEFT COLUMN GOSUB label
ON SCROLL RIGHT COLUMN GOSUB label

PURPOSE

This command is used to force a unconditional jump with returning to

a pre-defined position when the screen is scrolled down by an entire row
or column.
Abbreviated as ONSclGs

EXAMPLES
1 ON SCROLL UP ROW GOSUB scrolledAway

641
 15 Keywords

15.358 ON...GOSUB

SYNTAX
ON expression GOSUB label1[, label2 [, ... ] ]

PURPOSE
This command is used to force a unconditional jump with returning
to a pre-defined position when a specific expression is calculated. The
choice is done against several positions, and it depends on what value
is held by the expression at the time it is spotted.
To work properly, the expression must have a value from 1 up to the
number of the highest possible destination. If the expression has a value
of 0 or greater than the highest possibile destination, no jump will be
performed.

Abbreviated as ONGs
EXAMPLES
1 ON level GOSUB level1 , level2 , level3

642
 15.359 ON...GOTO

15.359 ON...GOTO

SYNTAX
ON expression GOTO label1[, label2[, ... ] ]

PURPOSE
This command is used to force a unconditional jump to a pre-defined
position when a specific expression is calculated. The choice is done
against several positions, and it depends on what value is held by the
expression at the time it is spotted.
To work properly, the expression must have a value from 1 up to the
number of the highest possible destination. If the expression has a value
of 0 or greater than the highest possibile destination, no jump will be
performed.

Abbreviated as ONGo
EXAMPLES
1 ON level GOTO level1 , level2 , level3

643
 15 Keywords

15.360 ON...PROC

SYNTAX
ON expression PROC name1[, name2 [, ... ] ]

PURPOSE
This command is used to force a call to subroutine when a specific
expression is calculated. The choice is done against several positions,
and it depends on what value is held by the expression at the time it is
spotted.
To work properly, the expression must have a value from 1 up to the
number of the highest possible destination. If the expression has a
value of 0 or greater than the highest possibile destination, no call will
be performed.

Important: if the OPTION CALL AS GOTO pragma is in effect, the in-

struction will be considered as a GOTO rather than a GOSUB. So, no
return value and no return, at all. This not applies to system calls.
Abbreviated as ONPrb

EXAMPLES
1 ON level PROC level1 , level2 , level3

644
 15.361 OPTION EXPLICIT

15.361 OPTION EXPLICIT

SYNTAX
OPTION EXPLICT [ON]
OPTION EXPLICT OFF

PURPOSE
When OPTION EXPLICT or OPTION EXPLICIT ON appears in a source
file, the programmer must explicitly declare all variables by using the
VAR or DIM statements.
If the programmer tries to use an undeclared variable name, an error
occurs at compile time. The OPTION EXPLICT OFF statement allows
implicit declaration of variables. If used, the OPTION EXPLICT state-
ment can appear everywhere in a source file, before any other source
code statements to check.
Setting OPTION EXPLICT OFF is generally not a good practice. The
programmer could misspell a variable name in one or more locations,
which would cause unexpected results when the program is run.

Abbreviated as OpEx1
EXAMPLES
1 OPTION EXPLICIT ON

645
15 Keywords

15.362 OR

SYNTAX
= x OR y

PURPOSE
Performs a logical disjunction on two expressions, as a bitwise disjunc-
tion. For comparisons managed as a boolean result (TRUE or FALSE),
result is TRUE if just one expresions evaluate to TRUE. The following
table shows how result is determined:
TRUE OR TRUE = TRUE
TRUE OR FALSE = TRUE
FALSE OR TRUE = TRUE
FALSE OR FALSE = FALSE

Generally speaking, the OR operator performs a bitwise comparison of

the bits of two numeric expressions and sets the corresponding bit in
result according to the previous table.
Note that ugBASIC uses the convention, very common in BASICs of the
1970s and 1980s, of considering Boolean logic as implemented through
the so-called ”two’s complement”.
In other words, the value FALSE is associated with a number composed
of all 0s, in terms of bits. The value TRUE is, instead, associated with a
number composed of all 1s, again in terms of bits. According to the 2’s
complement representation, a number composed of all ones is always
equivalent to the number -1, regardless of how many bits the number is
composed of, while a number composed of all zeros is always equivalent
to zero.
According to this convention, there is a coincidence between bitwise

646
 15.362 OR

and logical operations: in fact, a bitwise OR, applied to all the bits
of the number, will be equivalent to the logical operation. Note that
the OR operator always evaluates both expressions, which can include
executing routine calls.

Because the logical and bitwise operators have lower precedence than
other arithmetic and relational operators, all bitwise operations must be
enclosed in parentheses to ensure accurate results.
If the operands consist of a SIGNED BYTE expression and a numeric
expression, converts the SIGNED BYTE expression to a numeric value
(-1 for TRUE and 0 for FALSE) and performs a bitwise operation. So,
the data type of the result is a numeric type appropriate for the data
types of both expressions.
EXAMPLES
1 IF x OR 1 THEN : PRINT " always executed " : ELSE : PRINT " never
executed ": ENDIF

647
 15 Keywords

15.363 ORANGE (constant)

SYNTAX
= ORANGE

PURPOSE
This keyword represents the color orange. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (161, 104, 60). How-
ever, not all computers have this color. In which case, it is approximated
by the closest color available, which is usually also used in decoding im-
ages to identify the color to use.
Abbreviated as Or

EXAMPLES
1 PEN ORANGE

648
 15.364 ORIGIN

15.364 ORIGIN

SYNTAX
ORIGIN x, y UP
ORIGIN x, y [DOWN]

PURPOSE
The ORIGIN command can be used to set the origin of the cartesian axes
with respect to which drawing instructions will operate. The command
accepts the coordinates x, y of the origin, and the indication whether
the Y axis is oriented upwards (UP) or downwards (DOWN). If not used,
the reference system by default is placed at the top left with the Y axis
downwards.
Abbreviated as Og

EXAMPLES
1 ORIGIN 100 , 100 UP

649
15 Keywords

15.365 OUT

SYNTAX
PAUSE [string,] time
OUT port, value

PURPOSE
The PAUSE command will pause a running program in a time-controlled
manner. In order to have an easy way of signaling such a pause to the
user, PAUSE offers the optional string parameter. The string is output
at the current cursor position and does not append a line feed. After
output, the cursor remains behind the output string, as with the PRINT
command.
The OUT command is a statement that allows your program to interact
directly with your computer’s hardware, specifically its input/output
(I/O) ports. This command is especially useful in contexts where you
want to control external devices connected to your computer, such as
printers, sound cards, or data acquisition devices.
When you use the OUT command, you specify a port address and a value
to send to that port. The port address identifies a particular hardware
device connected to your computer, while the value sent determines the
action the device will perform.
The use of the OUT command is highly dependent on the specific hard-
ware of your computer. The port addresses and values to send vary
depending on the type of device connected and the system configura-
tion.
Improper use of the OUT command can damage the hardware or cause
the system to malfunction. It is essential to have a thorough under-
standing of the hardware you are interacting with and to use this com-

650
 15.365 OUT

mand with caution.

Abbreviated as Ou
AVAILABLE ON

c128z coleco cpc msx1 sc3000 sg1000 vg5000 zx

EXAMPLES
1 PAUSE " Waiting ..." , 3
2 OUT & HBC00 , 0

651
 15 Keywords

15.366 PAGE 0 (constant)

SYNTAX
= PAGE 0

PURPOSE
Alias for PAGE A
Abbreviated as Pg0

EXAMPLES
1 IF SCREEN PAGE = PAGE 0 THEN
2 PRINT " I am showing the page 0!"
3 ENDIF

652
 15.367 PAGE 1 (constant)

15.367 PAGE 1 (constant)

SYNTAX
= PAGE 1

PURPOSE
Alias for PAGE B
Abbreviated as Pg1

EXAMPLES
1 IF SCREEN PAGE = PAGE 1 THEN
2 PRINT " I am showing the page 1!"
3 ENDIF

653
 15 Keywords

15.368 PAGE A (constant)

SYNTAX
= PAGE A
= PAGE B

PURPOSE
This constant can be used to identify the first of two buffers in a double
buffering screen.

This constant can be used to identify the second of two buffers in a

double buffering screen.
Alias for PAGE 0, PAGE 1
Abbreviated as PgA

EXAMPLES
1 IF SCREEN PAGE = PAGE A THEN
2 PRINT " I am showing the page A !"
3 ENDIF
4 IF SCREEN PAGE = PAGE B THEN
5 PRINT " I am showing the page B !"
6 ENDIF

654
 15.369 PAINT

15.369 PAINT

SYNTAX
PAINT (x,y)[, c[, b]]
PAINT x, y, fq

PURPOSE
The PAINT command is used in high resolution graphics modes, to fill
a shape with a specified colour.

The x,y are the coordinates of the point where the painting is to start.
c is the colour code of the colours to be used to paint. It must be
between 0 and COLOR COUNT and be one of the available colour set for
the working mode. If omitted, the current foreground colour is used.

The b parameter is the colour code of the border at which painting is

to stop. It must also be between 0 and 8, the painting will continue
over a border of any other colour. If omitted, the current foreground
colour is used.
There is also an alternative syntax for PAINT, that is used to fill enclosed
areas in the color of the specified color source ’¡fq¿’ (see HIRES), starting
from the starting point x, y. PAINT does nothing if the selected starting
point already has the desired color.
Abbreviated as P#
EXAMPLES
1 PAINT (100 ,100) , RED
2 PAINT 0 ,0 ,1

655
 15 Keywords

15.370 PAL (constant)

SYNTAX
= PAL

PURPOSE
The keyword PAL allows you to know if the target is running with a
video chipset that supports PAL standard.

Abbreviated as PAL
EXAMPLES
1 IF PAL THEN
2 PRINT " I am using the PAL video standard !"
3 ENDIF

656
 15.371 PALETTE

15.371 PALETTE

SYNTAX
PALETTE c0[,c1[,c2[,...]]]

PURPOSE
The PALETTE command allows you to define and modify the range of
colors that can be used to draw on the screen. You can give a number
for each element of the palette, sequentially. Thenumber is then used
to refer to the specific color when drawing shapes or objects. Thanks
to RGB function you can change the red, green and blue value of each
color in the palette, allowing you to create custom color combinations,
provided that the hardware allows it.
The palette is applied immediately to all the graphic elements on the
screen. This allows you to define a color palette that adapts to the
atmosphere of the game, creating particular visual effects. It allows to
create transition effects between different colors, simulating for example
the passage of time or changes in state. Finally, it customizes the
appearance of the interface, making it more attractive and functional.

The maximum number of colors that can be defined in a palette varies

depending on the video chipset and the mode selected.
See also RGB, COLOR
EXAMPLES
1 PALETTE WHITE , RED , GREEN , BLUE
2 PALETTE RGB (0 ,0 ,0) , RGB (255 ,0 ,0) , RGB (255 ,255 ,255)

657
 15 Keywords

15.372 PAPER (function)

SYNTAX
= PAPER$(expression)

PURPOSE
The PAPER$ command create a special control sequence (string) that
define the background color of the screen. This means that, whenever
the string is printed on the screen, the pre-set paper colour is automati-
cally assigned to it. The format of the string returned by PAPER$ is not
specific for the target. The parameter color is represented by a value
in the available colors, from 0 to maximum (PAPER COLORS).
See also PEN (instruction), PAPER (instruction)

Abbreviated as Pa
EXAMPLES
1 PRINT PAPER$ ( WHITE )

658
 15.373 PAPER (instruction)

15.373 PAPER (instruction)

SYNTAX
PAPER color

PURPOSE
The PAPER command define the background color of the screen. Imag-
ine having a blank sheet of paper to draw on: with PAPER, you can
choose the color of this sheet, turning it into a colored sheet, lined
or squared, depending on your preferences and the capabilities of your
computer.
The parameter color is represented by a value in the available colors,
from 0 to maximum (PAPER COLORS). For the very specific reasons,
each color is encoded by a literal constant, like WHITE or YELLOW. Those
constants will be replaced by proper color index or values, depending
on the hardware. Obviously, you can directly put the numeric value for
the color, but you have to know the underlying encoding of the colors.
By combining the background color (defined with PAPER) with the color
of the text or lines (defined with PEN), you can create interesting visual
effects and improve the readability of your programs. You can also use
PAPER to create colored backgrounds that simulate different environ-
ments, such as a starry sky, a green meadow or a blue ocean. In simple
games, PAPER allows you to define the game background, creating a
more immersive atmosphere.

So the graphics capabilities of the PAPER command are closely tied to

the capabilities of the target running the program. The resolution of the
screen affected the quality of the colors displayed. On lower-resolution
screens, colors could appear less sharp. Some systems offers a wider
color gamut and more flexibility in defining colors. Others use a limited
color palette could result in some uniformity in the colors available. In

659
 15 Keywords

some target you can define your own palettes, so there is no guarantee
that the constants and values are the same.
You can use the DEFAULT constant to use the default paper color for
the considered target, again if no color replacement has been done.

See also PEN (instruction), PAPER (function)

Abbreviated as Pa
EXAMPLES
1 PAPER GREEN
2 PAPER colore

660
 15.374 PAPER COLORS (constant)

15.374 PAPER COLORS (constant)

SYNTAX
= PAPER COLORS

PURPOSE
This constant gives the number of colors that can be used with the
PAPER command. It usually represents the maximum number of colors
that can be managed in text mode, and has little to do with the actual
number of colors available in the mode in use. For that, it is advisable
to use the COLORS constant.
See also COLORS (constant)
Abbreviated as PaCrs

661
 15 Keywords

15.375 PARAM

SYNTAX
= PARAM(name)
= PARAM$(name)

PURPOSE
The PARAM function takes the result of an expression in an END PROC /
END PROCEDURE statement (or from a RETURN statement), and returns
it. If the variable you are interested in is a string variable, the $ character
can be used (but it is not mandatory).
Abbreviated as Pm
EXAMPLES
1 CALL factorial
2 x = PARAM ( factorial )

662
 15.376 PCLS

15.376 PCLS

SYNTAX
PURPOSE

Alias for CLS

Abbreviated as Pc

663
 15 Keywords

15.377 PEACH (constant)

SYNTAX
= PEACH

PURPOSE
This keyword represents the color peach. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as Pch

EXAMPLES
1 PEN PEACH

664
 15.378 PEEK

15.378 PEEK

SYNTAX
= PEEK( address )

PURPOSE
PEEK is a command that allows you to ”peek” into your computer’s
memory. In practice, it allows you to read the value stored in a specific
memory cell.

When using PEEK, you give the command the memory address you
want to know the contents of. The command will then return the
numeric value (a byte) stored at that address.
PEEK allows you to read data directly from memory, without going
through the normal program variables. On some systems, it is possible
to read the state of input/output ports using PEEK. With caution, PEEK
can be used to access memory reserved for the operating system, or the
ugBASIC program. Although it is generally discouraged, as it can cause
system instability or crashes, it can also speed up some operations.
The use of PEEK is highly dependent on the computer architecture and
operating system. Valid memory addresses and the meaning of the
values read may vary from one system to another. Improper use of
PEEK can cause damage to your system or corrupt data. It is important
to have a thorough understanding of how your computer works before
using this command.

See also PEEKW, PEEKD, D!PEEKW

Abbreviated as Pk
EXAMPLES
1 x = PEEK (1024)

665
 15 Keywords

15.379 PEEK MESSAGE

SYNTAX
= PEEK MESSAGE( portId )

PURPOSE
The PEEK MESSAGE function can be used to wait for a message on a
DOJO port. The function returns FALSE if the the message port is
empty. On the contrary, if it returns TRUE, it is possible to fetch the
message using the GET MESSAGE command.
Note that the message port behaves like a queue, that is, the first
message that is inserted is the first that is retrieved. Therefore, if a
program sends three messages in a row to the attention of the port
of another, the receiving program will receive the three messages in
the same order. Obviously, if several programs do the same thing, the
messages will be interspersed but, in the end, they will be in the same
order.
Alias for DOJO PEEK MESSAGE

Abbreviated as PkMsg
AVAILABLE ON
c64 c64reu coco coco3
EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = FIND ( sessionId , " user2 " , " testApp " )
3 IF PEEK MESSAGE ( port ) THEN
4 PRINT " A message is arrived !"
5 ENDIF

666
 15.380 PEEKD

15.380 PEEKD

SYNTAX
= PEEKD( address )

PURPOSE
PEEKD is a command that allows you to ”peek” into your computer’s
memory. In practice, it allows you to read the value stored in a specific
memory cell.

When using PEEKD, you give the command the memory address you
want to know the contents of. The command will then return the
numeric value (a double word) stored at that address.
PEEKD allows you to read data directly from memory, without going
through the normal program variables. On some systems, it is possible
to read the state of input/output ports using PEEKD. With caution,
PEEKD can be used to access memory reserved for the operating system,
or the ugBASIC program. Although it is generally discouraged, as it can
cause system instability or crashes, it can also speed up some operations.
The use of PEEKD is highly dependent on the computer architecture
and operating system. Valid memory addresses and the meaning of
the values read may vary from one system to another. Improper use of
PEEKD can cause damage to your system or corrupt data. It is important
to have a thorough understanding of how your computer works before
using this command.

See also PEEK, PEEKW

Abbreviated as Pkd
EXAMPLES
1 x = PEEKD (1024)

667
15 Keywords

15.381 PEEKW

SYNTAX

= PEEKW( address )

PURPOSE
PEEKW is a command that allows you to ”peek” into your computer’s
memory. In practice, it allows you to read the value stored in a specific
memory cell.
When using PEEKW, you give the command the memory address you
want to know the contents of. The command will then return the
numeric value (a word) stored at that address.

PEEKW allows you to read data directly from memory, without going
through the normal program variables. On some systems, it is possible
to read the state of input/output ports using PEEKW. With caution,
PEEKW can be used to access memory reserved for the operating system,
or the ugBASIC program. Although it is generally discouraged, as it can
cause system instability or crashes, it can also speed up some operations.

The use of PEEKW is highly dependent on the computer architecture

and operating system. Valid memory addresses and the meaning of
the values read may vary from one system to another. Improper use of
PEEKW can cause damage to your system or corrupt data. It is important
to have a thorough understanding of how your computer works before
using this command.
Alias for D!PEEK
See also PEEK, PEEKD
Abbreviated as PEEK

668
 15.381 PEEKW

EXAMPLES
1 x = PEEKW (1024)

669
 15 Keywords

15.382 PEN (function)

SYNTAX
= PEN$(expression)

PURPOSE
The PEN$ command create a special control sequence (string) that
define the foreground color of the screen. This means that, whenever
the string is printed on the screen, the pre-set pen colour is automatically
assigned to it. The format of the string returned by PEN$ is not specific
for the target. The parameter color is represented by a value in the
available colors, from 0 to maximum (PAPER COLORS).
See also PEN (instruction), PAPER (function)

Abbreviated as Pn
EXAMPLES
1 PRINT PEN$ ( RED )

670
 15.383 PEN (instrucion)

15.383 PEN (instrucion)

SYNTAX

PEN color

PURPOSE
The PEN command define the color that will be used to draw lines,
shapes, or write text on the screen. In practice, it is like choosing
the color of a pen or marker before you start drawing. Depending on
the hardware capabilities of the computer, the range of colors available
could be limited or very large. Some systems used predefined color
palettes, while others allowed you to define your own colors.
In order to be isomorphic, the color parameter repesents a value in
the available colors, from 0 to maximum (PEN COLORS). For the very
specific reasons, each color is encoded by a literal constant, like WHITE
or YELLOW. Those constants will be replaced by proper color index or
values, depending on the hardware. Obviously, you can directly put
the numeric value for the color, but you have to know the underlying
encoding of the colors.

So the graphics capabilities of the PEN command are closely tied to the
capabilities of the target running the program. The resolution of the
screen affected the quality of the colors displayed. On lower-resolution
screens, colors could appear less sharp. Some systems offers a wider
color gamut and more flexibility in defining colors. Others use a limited
color palette could result in some uniformity in the colors available. In
some target you can define your own palettes, so there is no guarantee
that the constants and values are the same.
You can use the DEFAULT constant to use the default pen color for the
considered target, again if no color replacement has been done.

671
 15 Keywords

Alias for INK

See also PAPER (instruction)
Abbreviated as Pn

EXAMPLES
1 PEN 4
2 PEN esempio

672
 15.384 PEN COLORS (constant)

15.384 PEN COLORS (constant)

SYNTAX
= PEN COLORS

PURPOSE
This constant gives the number of colors that can be used with the
PEN command. It usually represents the maximum number of colors
that can be managed in text mode, and has little to do with the actual
number of colors available in the mode in use. For that, it is advisable
to use the COLORS constant.
See also COLORS (constant)
Abbreviated as PnCrs

673
 15 Keywords

15.385 PERIOD (constant)

SYNTAX
= HOME

PURPOSE
This constant represent the ”PERIOD” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Per
EXAMPLES
1 IF KET STATE ( HOME ) THEN
2 PRINT " HOME has been pressed !"
3 ENDIF

674
 15.386 PI (constant)

15.386 PI (constant)

SYNTAX
= PI

PURPOSE
The PI constant is a mathematical constant that indicates the ratio
of the circumference of a circle to its diameter. The value of PI is
approximately 3.14159. It is a fundamental constant in many geometric
and trigonometric calculations.
Abbreviated as Pi
EXAMPLES
1 c = PI * 2 * r

675
 15 Keywords

15.387 PICK

SYNTAX
= PICK( string, offset )

PURPOSE
The PICK function allows you to obtain the ASCII code of any character
present in a string, provided that the offset within the string is provided.

EXAMPLES
1 PRINT PICK ( " TEST " , 2 )

676
 15.388 PING

15.388 PING

SYNTAX
= PING()

PURPOSE
The PING function lets you know if there is a DOJO server available or
running at the time you call it.

Alias for DOJO LOGIN

Abbreviated as Pin
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 IF PING ( ) THEN
2 PRINT " DOJO is available "
3 ENDIF

677
 15 Keywords

15.389 PINK (constant)

SYNTAX
= PINK

PURPOSE
This keyword represents the color pink. Depending on the methodology
and technique, as well as the available hardware, it can correspond to a
specific color in the RGB space. However, not all computers have this
color. In which case, it is approximated by the closest color available,
which is usually also used in decoding images to identify the color to
use.
Abbreviated as Pik

EXAMPLES
1 PEN PINK

678
 15.390 PLACE

15.390 PLACE

SYNTAX
= PLACE( text, searched [, start] )

PURPOSE
Alias for PLACE
Abbreviated as Pla

EXAMPLES
1 x = PLACE ( " ugBASIC " , " A " )
2 x = PLACE ( " ugBASIC " , " A " , 2 )

679
 15 Keywords

15.391 PLAY (instruction)

SYNTAX
PLAY #note[, #duration] [ON #channels]

PURPOSE
This command allows you to play a certain note, for a certain time and
on certain channels. The command has a number of variations. First,
you can omit the channel. In this case, the sound will be played on
all channels (or on those enabled by the VOICES/CHANNELS command).
Then you can omit the duration, in which case the sound will continue
to play while the next instruction is executed. Duration is expressed in
milliseconds.
Abbreviated as Py

AVAILABLE ON
atari atarixl c128 c64 coleco cpc msx1 plus4 sc3000 sg1000
EXAMPLES
1 PLAY #32
2 PLAY #24 , #250
3 PLAY #60 , #1250 ON #%001

680
 15.392 PLAY (program)

15.392 PLAY (program)

SYNTAX
PLAY string

PURPOSE
The PLAY allows you to generate music directly from your computer,
turning it into a real musical instrument. The PLAY command uses a
specific syntax to describe notes, duration, volume, and other musical
parameters.
Musical notes can be specified using the letters A through G, with
numbers to indicate the octave, or a number from 1 to 9. The duration
of a note can be specified with the letter L. To insert a rest, use the
letter P. The octave can be specified with the letter O followed by a
number. The tempo of the song can be changed with the T command,
while the volume can be changed using the V letter.
Abbreviated as Py
EXAMPLES
1 PLAY " O1V31T2L4GGL8GGL4B - AAGGF + G "

681
 15 Keywords

15.393 PLAY OFF

SYNTAX
PLAY OFF [ON #channels]

PURPOSE
This command allows you to stop the play on all channels or specific
channels.

Abbreviated as PyOf
AVAILABLE ON
atari atarixl c128 c64 coleco cpc msx1 plus4 sc3000 sg1000
EXAMPLES
1 PLAY OFF
2 PLAY OFF ON #%001

682
 15.394 PLOT

15.394 PLOT

SYNTAX
PLOT [x], [y][, color]

PURPOSE
The PLOT command allows you to draw individual points on the screen,
laying the foundation for creating more complex shapes such as lines or
rectangles. The origin (0,0) is usually located in the upper left corner
of the screen, but can be changed using ORIGIN command. The coor-
dinates increase to the right (for x) and down (for y), at least if the y
axis is inverted using always the ORIGIN. If the color is not provided,
the default color is the one set with the last INK / PEN command. It
is possible to omit one or both coordinates, and ugBASIC will use the
last one used, which is stored in the XGR and YGR variables.
The PLOT command is the starting point for any drawing. By drawing
a series of points close together, you can create the illusion of a line.
By combining lines, you can create geometric shapes such as rectan-
gles, triangles, and circles. By sequentially changing the coordinates of
points, you can create rudimentary animations,
The accuracy of your drawings is limited by your screen resolution,
and drawing a large number of points can be slow, especially on less
powerful computers. The ugBASIC language offers commands to draw
lines, rectangles, and circles more efficiently, but PLOT is the foundation.

Abbreviated as Pl
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc d32 d64 mo5 msx1
pc128op plus4 sc3000 sg1000 to8 vg5000 vic20 zx

683
 15 Keywords

EXAMPLES
1 PLOT 42 , 42
2 PLOT 100 , 100 , RED

684
 15.395 PLUS (constant)

15.395 PLUS (constant)

SYNTAX
= PLUS

PURPOSE
This constant represent the ”PLUS” key, when used as a value to com-
pare with SCANCODE,KEY STATE and KEY PRESSED. If the key does not
exist in the corresponding target, the value will be zero.

Abbreviated as Plu
EXAMPLES
1 IF KET STATE ( PLUS ) THEN
2 PRINT " PLUS has been pressed !"
3 ENDIF

685
 15 Keywords

15.396 PMODE

SYNTAX
PMODE mode, startpage

PURPOSE
The instruction PMODE allow to select the mode and startpage, using
the Dragon BASIC syntax. The mode is a number from 0 to 4, and
startpage is the page in video RAM you wish to start writing to.

Abbreviated as Pmd
AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc d32 d64 mo5 msx1
pc128op plus4 sc3000 sg1000 to8

EXAMPLES
1 PMODE 1 , 1

686
 15.397 POINT (function)

15.397 POINT (function)

SYNTAX
= POINT( x, y )

PURPOSE
The POINT function allows you to get the color presents a certain co-
ordinate of the screen.

Abbreviated as Pt
AVAILABLE ON
atari c128 c128z c64 coco coleco cpc d32 d64 mo5 msx1 pc128op
plus4 sc3000 sg1000 to8 vg5000 vic20 zx

EXAMPLES
1 c = POINT ( 42 , 42 )

687
 15 Keywords

15.398 POINT AT

SYNTAX
POINT AT ( [x], [y] )
POINT AT(#x, #y)
POINT AT(x, y)

PURPOSE

The POINT AT instruction allows you to draw a point on the screen, at

the (x, y) coordinate. The color is the default color, the one set with
the last INK / PEN command.
Abbreviated as PtAt
AVAILABLE ON

c128
EXAMPLES
1 POINT AT ( 42 , 42 )
2 POINT AT (42 , 42)
3 POINT AT (100 , 100)
4 POINT AT ( x +1 , y +1)

688
 15.399 POKE

15.399 POKE

SYNTAX
POKE address, value

PURPOSE
The POKE is the write equivalent of the PEEK command, meaning it
allows you to modify the contents of a specific memory cell. Essentially,
POKE allows you to ”write” a numeric value to a particular location in
your computer’s memory.
In many 8-bit systems, POKE was used to directly configure hardware,
such as changing the color of the screen or the sound. By combining
POKE with PEEK, you could create custom graphics and sound effects,
going beyond the standard ugBASIC capabilities.

POKE gives you very fine-grained control over your computer’s memory,
and it allows you to create special effects and customizations that would
otherwise be impossible. It is a great tool for understanding how a
computer works internally.

Improper use of POKE can cause your computer to freeze or corrupt

data. Randomly modifying memory can have unpredictable conse-
quences. Valid memory addresses and their meanings vary from system
to system.
See also POKEW, POKED, D!POKE

Abbreviated as Po
EXAMPLES
1 POKE 32768 , 2

689
 15 Keywords

15.400 POKED

SYNTAX
POKED address, value

PURPOSE
The POKED is the write equivalent of the PEEKD command, meaning it
allows you to modify the contents of four memory cells. Essentially,
POKED allows you to ”write” a numeric value to a particular location in
your computer’s memory.
In many 8-bit systems, POKED was used to directly configure hardware,
such as changing the color of the screen or the sound. By combining
POKED with PEEKD, you could create custom graphics and sound effects,
going beyond the standard ugBASIC capabilities.

POKED gives you very fine-grained control over your computer’s memory,
and it allows you to create special effects and customizations that would
otherwise be impossible. It is a great tool for understanding how a
computer works internally.

Improper use of POKED can cause your computer to freeze or corrupt

data. Randomly modifying memory can have unpredictable conse-
quences. Valid memory addresses and their meanings vary from system
to system.
See also POKE, POKEW

Abbreviated as Pod
EXAMPLES
1 POKED 32768 , 2

690
 15.401 POKEW

15.401 POKEW

SYNTAX
POKEW address, value

PURPOSE
The POKEW is the write equivalent of the PEEKW command, meaning
it allows you to modify the contents of two memory cells. Essentially,
POKEW allows you to ”write” a numeric value to a particular location in
your computer’s memory.
In many 8-bit systems, POKEW was used to directly configure hardware,
such as changing the color of the screen or the sound. By combining
POKEW with PEEKW, you could create custom graphics and sound effects,
going beyond the standard ugBASIC capabilities.

POKEW gives you very fine-grained control over your computer’s memory,
and it allows you to create special effects and customizations that would
otherwise be impossible. It is a great tool for understanding how a
computer works internally.

Improper use of POKEW can cause your computer to freeze or corrupt

data. Randomly modifying memory can have unpredictable conse-
quences. Valid memory addresses and their meanings vary from system
to system.
Alias for D!POKE

See also POKE, POKED

Abbreviated as POKE
EXAMPLES
1 POKEW 32768 , 2

691
 15 Keywords

15.402 POLYLINE

SYNTAX
POLYLINE [[x1],[y1]] TO [x2],[y2] [TO [x3],[y3] [TO [x4],[y4]]]...

PURPOSE
The POLYLINE command allows you to draw a certain number of con-
catenated lines.

Abbreviated as Ply
EXAMPLES
1 POLYLINE 10 ,10 TO 20 ,10 TO 20 ,20 TO 10 ,20 TO 10 ,10

692
 15.403 POP

15.403 POP

SYNTAX
POP

PURPOSE
Remove the caller address from GOSUB call. So you can do a GOTO
instead of RETURN.

See also RETURN, GOSUB

Abbreviated as Pp
EXAMPLES
1 POP

693
 15 Keywords

15.404 POP PROCEDURE

SYNTAX
POP PROCEDURE

PURPOSE
Alias for EXIT PROCEDURE, EXIT PROC
Abbreviated as PpPrcd

EXAMPLES
1 POP PROCEDURE

694
 15.405 POSITION (data type)

15.405 POSITION (data type)

SYNTAX
... AS POSITION

PURPOSE
The POSITION is a data type that represent a coordinate into the video
chipset.

Abbreviated as Ps
EXAMPLES
1 DIM x AS POSITION

695
 15 Keywords

15.406 POUND (constant)

SYNTAX
= POUND

PURPOSE
This constant represent the ”POUND” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Pnd
EXAMPLES
1 IF KET STATE ( POUND ) THEN
2 PRINT " POUND has been pressed !"
3 ENDIF

696
 15.407 POW

15.407 POW

SYNTAX
= POW( base, exponent )
= base e
^xponent

PURPOSE
The POW instruction is short for ”power” and is used to calculate the
power of a number. In other words, it allows you to raise a base number
to a certain exponent. It multiplies the base by itself a number of times
equal to the exponent. For example, POW(2, 3) means to multiply
2 by itself 3 times: 2 * 2 * 2. The variables used for the base and
exponent must be integer. So can be computationally expensive for very
large exponents. In some cases, there may be more efficient algorithms
for calculating powers.
EXAMPLES
1 pitagora = POW (a ,2) + b ^2 + POW (c ,2)

697
15 Keywords

15.408 PRINT

SYNTAX
PRINT [expr] [; [expr] [; ...] ... ]
PRINT [expr] [, [expr] [, ...] ... ]
PRINT @expr, [, [expr] [, ...] ... ]

PURPOSE
The PRINT instruction displays information on the screen, starting from
the current cursor position. An item or a list of items can follow the
command. If any item is omitted, a blank line is printed. The list of
items can consist of any group of strings, variables or constants. Each
element in the list must be separated by either a semi-colon ; or a
comma ,. A semi-colon prints the data immediately after the previous
value, whereas a comma first moves the cursor to the next TAB position
on the screen.
Normally the cursor will be advanced downwards by a single line after
each PRINT instruction. This can be suppressed by adding a separator
after the print. As before, a semicolon will preserve the cursor position
after the operation, and a comma will place the cursor to the next TAB
stop before proceeding.
All data printed to the screen is formatted by using the specific for-
matter for numbers, and ”as is” for strings, while complex data will be
printed out with an unique decription string. For the numeric data, the
numbers are always translated into decimal system. Nothing is written
if parameter is omitted.
Because the PRINT instruction prints with mono-spaced characters,
there is a correlation between the number of characters printed and
the number of columns those characters occupy. This ensures that
each character uses only one column. You can use the SPC keyword to

698
 15.408 PRINT

print after a specific number of spaces.

It is also possible to put the output to a specific location. The PRINT
@ command is used to place output at a specified place on the screen.
For this purpose the screen is divided into a SCREEN COLUMNS x SCREEN
ROWS grid, giving a certain amount of positions. The expression after
the @ can be a number, a variable or an arithmetic expression, as long
as the value is between 0 and ((SCREEN COLUMNS*SCREEN ROWS)-1).
Abbreviated as ?

EXAMPLES
1 PRINT " HELLO WORLD !"
2 PRINT ( a + b ) ;" IS A SUM !";
3 PRINT @100 , " HELLO WORLD !"

699
 15 Keywords

15.409 PRINT BUFFER

SYNTAX
PRINT BUFFER [expression];|,[expression]|;[expression] ...

PURPOSE
Abbreviated as ?Bf
EXAMPLES
1 file := load (" example . txt ")
2 PRINT BUFFER file

700
 15.410 PROC

15.410 PROC

SYNTAX
PROC name

PURPOSE
This keyword has multiple meaning. If the identifier that follows this
command is not already defined, this can be used to give a label (name)
to a pat of the program. This makes subprograms independent of their
position in the program and makes it easier for the programmer to
keep track of things (names are easier to assign to a purpose than line
numbers). The PROC command is used to define the name of such a
subprogram (or jump target). The name may consist of several words
separated by spaces. A leading space is not significant. Other BASIC
commands may be in the same line as PROC.
If, instead, the identifier has been already used for a procedure, then
this command will call the procedure, as the instruction CALL.
Abbreviated as Prb

EXAMPLES
1 PROC factorial

701
15 Keywords

15.411 PROCEDURE...END PROC

SYNTAX

PROCEDURE name[ par1[, par2[, ... ]]] ]

...
END PROC[ expression ]

PURPOSE

This couple of keywords create a procedure by giving it a name. The

name is then followed by a list of parameters and the procedure must
be ended with an END PROC command. PROCEDURE and END PROC
commands should be placed on their own individual lines, but it is not
mandatory.

Following the convention in other BASICs of the time, such as Simon’s

BASIC or Tuned Simon’s BASIC, the procedure name can also contain
spaces. In this case, the trailing space will not be considered as part of
the name.
It is possible to place the procedure definition anywhere in the program.
When ugBASIC encounters a procedure statement, the procedure is
recognised and a jump is made to the final END PROC. In this way,
there is no risk of executing your procedure by accident.
Following the procedure’s name can be given a list of parameters. This
creates a group of local variables that can be loaded directly from the
main program. Note that the values to be loaded into parameters
must be entered between square brackets as part of the procedure call.
This system works equally well with constants as well as variables, but
although you are allowed to transfer integer, real or string variables, you
may transfer also arrays using this method. If you need to enter more
than one parameter, the variables must be separated by commas.

702
 15.411 PROCEDURE...END PROC

As an option, you can specify a value for the function to return. The
value must be indicated in square brackets ([...]). The value will then
be copied into the PARAM variable and returned by the call, if the call
was made in the context of an expression.

Important: if the OPTION CALL AS GOTO pragma is in effect, the in-

struction will be considered as a NOP.
Abbreviated as PrcdEePrb
EXAMPLES
1 PROCEDURE test [ a , b ]
2 DEBUG " HELLO WORLD ! "; ( a + b )
3 END PROC
4 PROCEDURE sumOf ( x , y )
5 END PROC [ x + y ]
6 PROCEDURE hundred
7 END PROC [100]

703
 15 Keywords

15.412 PURPLE (constant)

SYNTAX
= PURPLE

PURPOSE
This keyword represents the color purple. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as Pur

EXAMPLES
1 PEN PURPLE

704
 15.413 PUT BITMAP

15.413 PUT BITMAP

SYNTAX
PUT BITMAP resource [ AT [x],[y] ] [DOUBLE Y]
PUT BITMAP resource FRAME f [ AT [x],[y] ] [DOUBLE Y]
PUT BITMAP resource STRIP s FRAME f [ AT [x],[y] ] [DOUBLE
Y]

PURPOSE

This function draws the bitmap component of an image at a specific

position on the screen. The programmer can draw on the screen a single
bitmap (IMAGE), a frame of a series of bitmaps (ATLAS) or a frame of
a strip of a sequence of bitmaps (SEQUENCE). In all cases the syntax
changes slightly.

Every PUT BITMAP can be followed by a flag that modify the wayt the
image will be drawn on the screen. The DOUBLE Y flag will double the
vertical size of the image. This flag could be not available on all targerts
and graphical modes.
See also PUT IMAGE

Abbreviated as PuBm
EXAMPLES
1 PUT BITMAP airplane AT 10 ,10

705
15 Keywords

15.414 PUT IMAGE

SYNTAX
PUT IMAGE resource AT [x],[y]
PUT IMAGE resource FRAME frame AT [x],[y]
PUT IMAGE resource STRIP sequence FRAME frame AT [x],[y]
PUT IMAGE resource [ AT [x],[y] ] [fl]
PUT IMAGE resource FRAME f [ AT [x],[y] ] [fl]
PUT IMAGE resource STRIP s FRAME f [ AT [x],[y] ] [fl]
fl: [WITH TRANSPARENCY] [DOUBLE Y]
PUT ([x1],[y1])-(x2,y2),resource[,fl2]
fl2: PSET|PRESET|AND|OR|NOT

PURPOSE
This function draws an image at a specific position on the screen. The
programmer can draw on the screen a single image (IMAGE), a frame
of a series of images (IMAGES) or a frame of a pose of a sequence of
images (SEQUENCES). In all cases the syntax changes slightly.
This function draws an image at a specific position on the screen. The
programmer can draw on the screen a single image (IMAGE), a frame of
a series of images (ATLAS) or a frame of a strip of a sequence of images
(SEQUENCE). In all cases the syntax changes slightly.
Every PUT IMAGE can be followed by a flag that modify the wayt the
image will be drawn on the screen. The WITH TRANSPARENCY will en-
able the transparency effect when the image is drawn, while DOUBLE
Y will double the vertical size of the image. Both flags could be not
available on all targerts and graphical modes.
Another syntax is more compatible with other BASICs, that requires
that the PUT IMAGE is followed with the bounds to draw to. This is
only a syntatic equivalence, there is no ”clipping” around the bounds.

706
 15.414 PUT IMAGE

Moreover, it is possible to give a flag that alter the default behaviour of

PUT IMAGE. The PSET is the standard behaviour of PUT IMAGE, while
PRESET will put only the bitmap part of the image (if possible). The
AND and OR flags will activate the same logical operation between the
image and the background. NOT is not currently supported.
See also PUT BITMAP
Abbreviated as PuIm
EXAMPLES
1 PUT IMAGE airplane AT 10 ,10

707
 15 Keywords

15.415 PUT KEY

SYNTAX
PUT KEY string

PURPOSE
The PUT KEY command allows you to simulate pressing a key on your
computer keyboard. Basically, you enter a string of characters and
ugBASIC will use it as if they were typed one after the other. This can
be very useful for automating certain actions, such as automatically
entering your password or emulating keystrokes.
This can be used to automatically enters a password into a game or
application, or to simulate an user interaction with the program itself,
such as pressing a button or selecting a menu. It can help to cre-
ate sequences of commands that are executed automatically, such as a
macro.
The maximum length of the string you can enter depends on the key-
board buffer, but normally is up to 10 characters.

Abbreviated as PuKy
EXAMPLES
1 PUT KEY " yes "

708
 15.416 PUT MESSAGE

15.416 PUT MESSAGE

SYNTAX
PUT MESSAGE portId, string

PURPOSE
The PUT MESSAGE allows to put a message on a specific port. This
is a statement, not a function. It follows that we cannot know if the
statement was successful. This does not really represent a limitation,
for the simple fact that the statement will always be successful: if
the program on the other side of the port is not available, for some
reason, the message will be preserved by the DOJO server, and it will
be delivered at the first available moment.
Alias for DOJO PUT MESSAGE

Abbreviated as PuMsg
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 sessionId = LOGIN ( " user " , " password " )
2 port = FIND ( sessionId , " user2 " , " testApp " )
3 PUT MESSAGE port , " hello !"

709
15 Keywords

15.417 PUT TILE

SYNTAX
PURPOSE

Abbreviated as PuTl

710
 15.418 PUT TILEMAP

15.418 PUT TILEMAP

SYNTAX
PUT TILEMAP resource [ LAYER layer ] [ FROM x, y ]

PURPOSE
The command PUT TILEMAP can be used to draw a map on the screen.
Note how the same map draws the same way on different screens. The
map is however within the available screen size. If the map is bigger
than the screen, the comamnd only draws a part of the map. To scroll
the map you can use the FROM parameter with the offsets (in terms of
tiles) starting from which the map will have to be drawn on the screen.
Abbreviated as PuTm

EXAMPLES
1 PUT TILEMAP map

711
 15 Keywords

15.419 RADIAN

SYNTAX
RADIAN

PURPOSE
This command allows you to select the angle mode with trigonometric
functions, setting it to radiants.

Abbreviated as Rdn
EXAMPLES
1 DEGREE
2 x1 = COS (180)
3 RADIAN
4 x2 = COS (3.1415)
5 PRINT x1 ;" "; x2

712
 15.420 RANDOM

15.420 RANDOM

SYNTAX
= RANDOM type
= (type) RANDOM

PURPOSE
This function allows you to calculate a random number, in the range
that can be represented by the type of data indicated as a parameter,
or as data type conversion.
See also RND
Abbreviated as Rd

EXAMPLES
1 randomScore = RANDOM BYTE
2 randomColor = ( COLOR ) RANDOM

713
 15 Keywords

15.421 RANDOM HEIGHT

SYNTAX
= RANDOM HEIGHT

PURPOSE
Calculate a random height.
Abbreviated as RdHg

EXAMPLES
1 POINT AT ( RANDOM WIDTH , RANDOM HEIGHT )

714
 15.422 RANDOM WIDTH

15.422 RANDOM WIDTH

SYNTAX
= RANDOM WIDTH

PURPOSE
Calculate a random width.
Abbreviated as RdWd

EXAMPLES
1 POINT AT ( RANDOM WIDTH , RANDOM HEIGHT )

715
 15 Keywords

15.423 RANDOMIZE

SYNTAX
RANDOMIZE seed

PURPOSE
Initialize the random seed.
Abbreviated as Rdm

AVAILABLE ON
c128
EXAMPLES
1 RANDOMIZE

716
 15.424 RASTER AT

15.424 RASTER AT

SYNTAX

RASTER AT line WITH label

RASTER label AT line

PURPOSE
The RASTER AT instruction will set the next execution raster line for
a raster routine. A raster routine is a small program or sequence of
instructions that uses a particular moment in the screen display to be
activated. This is when the electron beam (the raster beam) scans the
screen, line by line, to draw the image.
The mechanism is simple. The computer generated an interrupt (a
signal that stopped the main program being executed) every time the
raster beam reached the given line on this instruction. When the in-
terrupt occurred, the processor passed execution to the raster routine.
The routine directly does something, like modify the video memory o
registers. Once the change was complete (by using the instruction NEXT
RASTER), the processor would resume execution of the main program
from where it had stopped.
Using this mechanism, programmers could create very simple, but often
surprisingly engaging, graphics, animations, and games, considering the
hardware limitations of the time. They were essential for creating effects
such as scrolling, moving sprites around the screen, creating explosion
or deformation effects.
Raster routines offers very precise control over image generation, allow-
ing for customized and optimized effects, and stimulated the creativity
of programmers, who could invent new ways to exploit the mechanism
to create innovative visual effects.

717
 15 Keywords

See also NEXT RASTER, NEXT RASTER AT

Abbreviated as RstAt
AVAILABLE ON

c128 c64 c64reu plus4 vic20

EXAMPLES
1 RASTER AT #& H42 WITH rasterRoutine
2 RASTER AT ( rasterLine +1) WITH rasterRoutine

718
 15.425 RASTER LINE

15.425 RASTER LINE

SYNTAX
= RASTER LINE

PURPOSE
The RASTER LINE keyword gives the current raster line, or the current
vertical position of a raster beam. A raster beam is a beam of electrons
or light that systematically scans an area, moving from left to right and
top to bottom, like the lines that form an image on a cathode ray tube
or CRT television. This movement creates a grid of points of light,
called pixels, that together form the complete image.
Imagine painting a picture with a brush. The brush moves from left to
right and then down a line, repeating this movement until the entire
surface is covered. The brush in this case represents the raster beam.
The raster line indicates the vertical position of the raster beam at
any given time. The values range of this position varies on the various
targets, and if a PAL or NTSC system is in use.
Having access to the the raster line can help optimize rendering, an-
imation, and image processing algorithms. If you experience display
problems, such as distorted lines or flickering images, analyzing raster
lines can help pinpoint the cause. Many applications, such as video
games and 3D graphics software, require precise control of the raster
beam to create complex visual effects.

Abbreviated as RstLn
AVAILABLE ON
atari atarixl c128 c64 c64reu plus4 vic20
EXAMPLES

719
 15 Keywords

1 randomScore = RASTER LINE

720
 15.426 READ

15.426 READ

SYNTAX
READ var

PURPOSE
The READ is used for reading constant values from DATA lines into the
given variables. This command is able to read more constants at once
with a variable list separated by commas.

If using the wrong type of variable (for example read a character string
into a numerical variable like float or integer), the variable will be un-
touched. Such behavior can be prevented by generally using a variable
of the same type like the DATA AS used.

With a value that falls outside the expected range of a READ variable,
e.g. the value is outside the range of an integer, ugBASIC will implicitly
convert it, with a precision lost, but only if SAFE keyword is used. If
more constants are read than values exist in DATA lines, garbare will
be read. It can be avoided by using SAFE keyword or using READ END
function. Using SAFE the variable will not be touched if last value is
already read.
A succeeding READ searches for the first DATA statement where the DATA
read pointer is adjusted to.
Abbreviated as R#

EXAMPLES
1 READ nextStep

721
 15 Keywords

15.427 READ END

SYNTAX
= READ END

PURPOSE
The READ END function allows you to know if you have reached the last
value to read with the READ command. If the function returns true, this
means that the next READ command will ignore the read.

Abbreviated as R#Ee
EXAMPLES
1 IF READ END THEN
2 RESTORE
3 ENDIF

722
 15.428 READY

15.428 READY

SYNTAX
= READY()

PURPOSE
The READY function lets you know if there is a byte available on DOJO
connection.

Alias for DOJO READY

Abbreviated as R#y
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 IF READY ( ) THEN
2 PRINT " DOJO data is available "
3 ENDIF

723
 15 Keywords

15.429 REC

SYNTAX
REC x, y, sa, sb, fq

PURPOSE
REC draws a rectangle. The location of the top left corner is determined
by the first two parameters x and y, the width and height of the rect-
angle by parameters three and four (sa and sb). The color of the edge
lines is determined by the last parameter (fq, color source). The four
corners of the rectangle are always drawn.
Permissible values are 0..SCREEN WIDTH for x and sa. For y or sb,
values from 0 to SCREEN HEIGHT are permitted in both cases. The color
also depends on the graphics mode and refers to the color specifications
behind HIRES on the one hand and MULTI and LOW COL on the other.
The point 0,0 is in the top left corner.
Note: If the edge lengths of the rectangle exceed the screen limits,
rectangle will be clipped.

Alias for BOX

Abbreviated as Rc
EXAMPLES
1 REC x , y , 29 , 19 , 1

724
 15.430 RECEIVE

15.430 RECEIVE

SYNTAX
= RECEIVE()

PURPOSE
The RECEIVE function waits for a character from DOJO connection.
Alias for DOJO RECEIVE

Abbreviated as Rcv
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 IF READY ( ) THEN
2 PRINT RECEIVE ()
3 ENDIF

725
 15 Keywords

15.431 RED (constant)

SYNTAX
= RED

PURPOSE
This keyword represents the color red. Depending on the methodology
and technique, as well as the available hardware, it can correspond to
a specific color in the RGB space, usually (255,0,0). However, not
all computers have this color. In which case, it is approximated by the
closest color available, which is usually also used in decoding images to
identify the color to use.
Abbreviated as Re

EXAMPLES
1 PEN RED

726
 15.432 REM

15.432 REM

SYNTAX

REM [comment]
’ [comment]

PURPOSE
In BASIC, the REM keyword (also abbreviated by the single quotation
character (’)) is used to insert comments into code. A comment is
a note or explanation that is added to code to make it easier for the
developer to understand, as well as for other programmers who may
read it in the future.
When the computer compile the ugBASIC program, it completely ig-
nores everything that follows the REM keyword on the same line. The
word REM can be placed at the beginning of a line or after a colon.
In either case, the rest of the line will be treated as a comment. To
comment out multiple lines of code, you can use REM at the beginning
of each line. Note that you cannot continue a REM statement by using
a line-continuation sequence ( ). This means that, for a multiple-line
comment, you need to use as many REMs statements as the lines you
comment.
Comments have the role to describe the purpose of a particular section
of code or individual statement, and it provide information about the
program, who created it, when it was created, and what changes were
made. They make code easier to understand, even for people who didn
write the program: when you return to code after some time, comments
help you remember the purpose of different parts of the program.
Moreover, it is the best way to disable a piece of code without deleting
it, simply add REM to the beginning of the line.

727
 15 Keywords

The main guidelines in using REM it to use simple, direct language to

explain the code, avoiding long or complicated sentences. Generally,
they should be used on parts of the code that are not obvious. You do
not need to comment on every single line.

EXAMPLES
1 REM this is a comment
2 ’ and this is a comment
3 PRINT " ok ": REM I am printing ok

728
 15.433 REMEMBER

15.433 REMEMBER

SYNTAX
REMEMBER

PURPOSE
The REMEMBER command restores the cursor position previously stored
by the MEMORIZE command. The REMEMBER command can be executed
multiple times, and this will restore the cursor position to the last stored
position. Note that the stored position refers to the current console. If
there are no consoles defined, one equal to full screen will be defined.
See also MEMORIZE
Abbreviated as Rm

EXAMPLES
1 REMEMBER

729
 15 Keywords

15.434 REPEAT...UNTIL

SYNTAX
REPEAT
...
UNTIL expression

PURPOSE

The ’REPEAT...UNTIL command will repeatedly execute a block of

code until a certain condition is met. In essence, it creates a loop that
continues to repeat until a specific exit condition is met.
When you don’t know exactly how many times you want to repeat a
block of code, but you want to continue until a certain condition is met,
this is the best command to use. For example, to repeatedly prompt the
user for input until they enter it correctly. Another usage is to perform
calculations that require multiple iterations, such as finding the square
root of a number using the Newton-Raphson method.
Make sure the condition inside UNTIL can become true at some point,
otherwise your program may end up in an infinite loop. If you need to
execute a loop a large number of times, consider optimizing your code
to improve performance.
See also DO...LOOP, WHILE...WEND, FOR...NEXT
Abbreviated as RptUn

EXAMPLES
1 REPEAT
2 score = score + 1
3 UNTIL alive

730
 15.435 RESOLUTION

15.435 RESOLUTION

SYNTAX
RESOLUTION width, height

PURPOSE
This keyword allows to have a ”virtual” resolution. Even when you
select a graphical mode with only 160 pixel x 200 pixel, the graphical
instructions execute the same thing, the only difference is that the
pixels will be proportional to virtual resolution. The choice to add
this instruction is guided by mathematical ratio, since 640x400 pixels
gives 1,6 where 640x200 gives 3,2. 1.6 isn’t a perfect 4/3 ratio but at
least it’s closer. By default, the virtual resolution will be set equal to
the resolution given by BITMAP ENABLE. Then, after RESOLUTION, the
graphical instructions will use this virtual resolution.
See also ORIGIN
Abbreviated as Res
EXAMPLES
1 RESOLUTION 100 , 100

731
 15 Keywords

15.436 RESPAWN (function)

SYNTAX
= RESPAWN(identifier)

PURPOSE
This keyword will restart a (finished) (parallel) procedure, giving back
a thread id.

Abbreviated as Rn
EXAMPLES
1 newHandle = RESPAWN ( f ac to ri a lH an d le )

732
 15.437 RESPAWN (instruction)

15.437 RESPAWN (instruction)

SYNTAX
RESPAWN identifier

PURPOSE
This keyword will restart a (finished) (parallel) procedure.
Abbreviated as Rn

EXAMPLES
1 RESPAWN factori al Ha n dl e

733
 15 Keywords

15.438 RESTORE

SYNTAX
RESTORE label

PURPOSE
The RESTORE command is used to reset the data read pointer to the
beginning of a list of DATA. Imagine having a cassette tape with numbers
on it, and you want to read those numbers one at a time. When you use
RESTORE, it’s as if you’re rewinding the tape to the beginning, ready to
read all the numbers again.
When the program encounters this command, the data read pointer is
automatically reset to the beginning of the first data list you defined.
If you give a parameter, you can set the pointer to the label given.

The RESTORE command is especially useful when you want to reuse a

list of data. If you need to read the same data multiple times in your
program, you can use RESTORE to reset the pointer to the beginning of
the list without having to retype it. If you want to read only part of the
data, you can use RESTORE to skip parts of the list and start reading
from a specific point. If you want to create loops that read the data,
by combining RESTORE with other commands such as READ and DATA,
you can create loops that repeatedly read the same data.
See also READ, DATA

Abbreviated as Rer
EXAMPLES
1 RESTORE inizio

734
 15.439 RETURN (constant)

15.439 RETURN (constant)

SYNTAX
= RETURN

PURPOSE
This constant represent the ”RETURN” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Rt
EXAMPLES
1 IF KET STATE ( RETURN ) THEN
2 PRINT " RETURN has been pressed !"
3 ENDIF

735
 15 Keywords

15.440 RETURN (instruction)

SYNTAX
RETURN

PURPOSE
Return from unconditional jump. The execution will continue to the
instruction next to the caller’s one.

See also GOSUB, POP

Abbreviated as Rt
EXAMPLES
1 RETURN

736
 15.441 RETURN (procedure)

15.441 RETURN (procedure)

SYNTAX
RETURN expression

PURPOSE
If you want to return a parameter from inside a procedure, that is to say,
if you need to send back a value from a local variable and/or expression,
you need a way of telling your main program where to find this local
variable. T
The RETURN instruction takes the result of an expression and put it into
the PARAM variable and it returns the expression like the result of the
calling procedure.

See also PROCEDURE

Abbreviated as Rt
EXAMPLES
1 RETURN 42

737
 15 Keywords

15.442 RGB

SYNTAX
= RGB( red, green, blue )

PURPOSE
The RGB function allows you to obtain the equivalent value of a color,
given its red, green and blue components. The value of this function,
where it is supported by the target, can be used in place of a nominal
color. Where it is not defined, it always returns a value of zero, which
may (or may not) correspond to a valid color.
See also COLOR, SHADES (constant)
EXAMPLES
1 red = RGB ( 255 , 0 , 0 )

738
 15.443 RIGHT (constant)

15.443 RIGHT (constant)

SYNTAX
= RIGHT

PURPOSE
This constant represent the ”RIGHT” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Rg
EXAMPLES
1 IF KET STATE ( RIGHT ) THEN
2 PRINT " RIGHT has been pressed !"
3 ENDIF

739
 15 Keywords

15.444 RIGHT (function)

SYNTAX
= RIGHT( text, position )

PURPOSE
The RIGHT function returns a (dynamic) string containing a specified
number of characters, from the right side of a given string. The function
has two parameters.

The first parameter is the string expression from which the rightmost
characters are returned. If string is empty, an empty string is returned.
The second parameter is a numeric expression, indicating how many
characters to return. If 0, an empty string ("") is returned. On the
other hand, if greater than or equal to the number of characters in
string, the entire string is returned, untouched.
To determine the number of characters in string, you should use the
LEN function.
See also RIGHT (instruction), LEFT (function), LEFT (instruction),
MID (function), MID (instruction), LEN
Abbreviated as Rg
EXAMPLES
1 x = RIGHT ( " TEST " , 2 )

740
 15.445 RIGHT (instruction)

15.445 RIGHT (instruction)

SYNTAX
RIGHT(text,position) = expression

PURPOSE
The RIGHT command replaces the rightmost characters in the destina-
tion string with the equivalent characters from the given strings. The
command has two parameters.

The first parameter is the string expression to change.

The second parameter is a numeric expression, indicating how many
characters to return. If 0, an empty string ("") is returned. On the
other hand, if greater than or equal to the number of characters in
string, the entire string is returned, untouched.
To determine the number of characters in string, you should use the
LEN function.
See also RIGHT (function), LEFT (function), LEFT (instruction),
MID (function), MID (instruction), LEN

Abbreviated as Rg
EXAMPLES
1 RIGHT ( " TEST " , 2 ) = " AM "

741
 15 Keywords

15.446 RIGHT ALT (constant)

SYNTAX
= RIGHT ALT

PURPOSE
This constant represent the left ”ALT” key, when used as bitmask for
KEY SHIFT instruction.

Alias for ALT RIGHT (constant)

Abbreviated as RgAl
EXAMPLES
1 IF KEY SHIFT AND RIGHT ALT THEN
2 PRINT " RIGHT ALT has been pressed !"
3 ENDIF

742
 15.447 RIGHT SHIFT (constant)

15.447 RIGHT SHIFT (constant)

SYNTAX
= RIGHT SHIFT

PURPOSE
This constant represent the right ”SHIFT” key, when used as bitmask
for KEY SHIFT instruction.

Alias for SHIFT RIGHT (constant)

Abbreviated as RgSHIFT
EXAMPLES
1 IF KEY SHIFT AND RIGHT SHIFT THEN
2 PRINT " RIGHT SHIFT has been pressed !"
3 ENDIF

743
 15 Keywords

15.448 RND

SYNTAX
= RND(max)

PURPOSE
The RND function generates integers at random, between zero and any
number specified in brackets (minus one). If your specified number
is greater than zero, random numbers will be generated up to that
maximum number.
EXAMPLES
1 score = score + RND (100)

744
 15.449 RND(0)

15.449 RND(0)

SYNTAX
= RND(0)

PURPOSE
The function RND(0) generates pseudo random floating point numbers
in the range of 0.0 (inclusive) to 1.0 (exclusive). By using RND(0),
it gives a different random number each time from a predetermined
sequence (the sequence number is stored internally).
Abbreviated as
EXAMPLES
1 value = 42.0 * RND (0)

745
 15 Keywords

15.450 RND(1)

SYNTAX
= RND(1)

PURPOSE
The function RND(1) generates pseudo random floating point numbers
in the range of 0.0 (inclusive) to 1.0 (exclusive). By using RND(1),
it gives a different random number each time from a predetermined
sequence (the sequence number is stored internally).
Abbreviated as
EXAMPLES
1 value = 42.0 * RND (1)

746
 15.451 ROT

15.451 ROT

SYNTAX
PURPOSE

The ROT command is used to set the starting angle and step for subse-
quent drawing operations with the DRAW command.
See also DRAW (program)
Abbreviated as Rot

EXAMPLES
1 DRAW " BM0 ,0; R10 ; U10 ; L10 ; D10 "

747
15 Keywords

15.452 ROWS (constant)

SYNTAX
= ROWS

PURPOSE
This constant gives you the number of rows of the actual console.
Alias for ROWS (constant)

Abbreviated as Rws

748
 15.453 RUN

15.453 RUN

SYNTAX
RUN

PURPOSE
the RUN command restarts the execution of a program. When the pro-
gram encounter this command, the computer begins executing from the
very firstr instructions in your program, one after the other.

EXAMPLES
1 RUN

749
 15 Keywords

15.454 RUN PARALLEL

SYNTAX
RUN PARALLEL

PURPOSE
This keyword will execute all previously invoked procedures.
Abbreviated as RUNPr

EXAMPLES
1 RUN PARALLEL

750
 15.455 RUN STOP (constant)

15.455 RUN STOP (constant)

SYNTAX
= RUN STOP

PURPOSE
This constant represent the ”RUN STOP” key, when used as a value
to compare with SCANCODE,KEY STATE and KEY PRESSED. If the key
does not exist in the corresponding target, the value will be zero.

Alias for RUNSTOP (constant)

Abbreviated as RUNSt

751
15 Keywords

15.456 RUNSTOP (constant)

SYNTAX
= RUNSTOP

PURPOSE
This constant represent the ”RUNSTOP” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as RUNSTOP

752
 15.457 SCANCODE

15.457 SCANCODE

SYNTAX
= SCANCODE

PURPOSE
The ”SCANCODE’ (or SCAN CODE) capture a single character typed by
the user without having to press enter. In other words, the program is
”listening” to the keyboard and, as soon as a key is pressed, ”captures”
it and stores it in a variable.
Like the INKEY command, it reads the character as soon as it is pressed.
If no key has been pressed, it returns NONE. The captured character
is stored in a BYTE variable, and it is in a target dependent encoding.
You must use the various constants to compare the value returned with
the key wanted.
It is used to create interactive games where the user can control the
character or objects by pressing specific keys, to create text menus
where the user can select an option by pressing a letter or number or
to create programs that respond to external events, such as pressing a
key to start or stop an action.
See also SCANCODE
Abbreviated as Scc
EXAMPLES
1 IF SCANCODE = KEY A THEN
2 PRINT " A has been pressed !"
3 ENDIF

753
 15 Keywords

15.458 SCREEN (constant)

SYNTAX
... = SCREEN
= SCREEN

PURPOSE
Retrieves a bitmask with screen characteristics, such as whether or not
TILE or BITMAP mode is available.

D
B̂IT POSITION ŜYMBOL M̂EANING —ˆ 0 — TILEMAP — Is tilemap

E
native? — — 1 — BITMAP — Is bitmap native? —
AT
This can be verified with a simple bitwise comparison.
The SCREEN constant represents the capabilities of video chipset.
EC
See also BITMAP (constant)
Abbreviated as Sc
PR

EXAMPLES
1 IF SCREEN IS TILEMAP THEN : PRINT " tilemap is native !": ENDIF
2 IF BIT BITMAP OF SCREEN THEN : PRINT " bitmap is available !":
ENDIF
DE

754
 15.459 SCREEN (instruction)

15.459 SCREEN (instruction)

SYNTAX
SCREEN #mode
SCREEN #type, #colorset

PURPOSE
The SCREEN command allows you to switch mode, from text mode
(where you can display only characters) to graphics mode, where you
can draw points, lines, and complex shapes on the screen.
Most games use graphics mode to display characters, scenery, and
animations. You can create slide shows and presentations with eye-
catching visuals, and you will have access to canvas to create digital
art.

The mode parameter represent a specific graphic mode, different from

target to target.
See also BITMAP ENABLE
Abbreviated as Sc

EXAMPLES
1 SCREEN #1
2 SCREEN #1 , #0

755
15 Keywords

15.460 SCREEN BORDER X (constant)

SYNTAX
= SCREEN BORDER X

PURPOSE
Returns the width of the border of the screen, in the reference frame
used by sprites. If no sprites are available, or if the border is not present,
it is equal to 0. This constant should be used as a horizontal offset, to
ensure that the sprite is visible beyond the left screen border.
Abbreviated as ScBoX

756
 15.461 SCREEN BORDER Y (constant)

15.461 SCREEN BORDER Y (constant)

SYNTAX
= SCREEN BORDER Y

PURPOSE
Returns the height of the border of the screen, in the reference frame
used by sprites. If no sprites are available, or if the border is not present,
it is equal to 0. This constant should be used as a vertical offset, to
ensure that the sprite is visible beyond the top screen border.
Abbreviated as ScBoY

757
15 Keywords

15.462 SCREEN COLORS (constant)

SYNTAX
= SCREEN COLORS

PURPOSE
Alias for COLORS.
Alias for COLORS (constant), COLORS COUNT (constant)

Abbreviated as ScCrs

758
 15.463 SCREEN COLOURS (constant)

15.463 SCREEN COLOURS (constant)

SYNTAX
= SCREEN COLORS

PURPOSE
Alias for COLORS.
Alias for COLOURS (constant), COLOURS COUNT (constant)

Abbreviated as ScCOLOURS

759
 15 Keywords

15.464 SCREEN COLUMNS (constant)

SYNTAX
= SCREEN COLUMNS

PURPOSE
Alias for SCREEN TILES WIDTH.
Alias for SCREEN TILES WIDTH (constant), TILES WIDTH (constant)

Abbreviated as ScCms
EXAMPLES
1 IF SCREEN COLUMNS > 40 THEN : PRINT " At least 40 columns !!":
ENDIF

760
 15.465 SCREEN COLUMNS (instruction)

15.465 SCREEN COLUMNS (instruction)

SYNTAX
PURPOSE

Abbreviated as ScCms
AVAILABLE ON
c128

761
15 Keywords

15.466 SCREEN COLUMNS (instructions)

SYNTAX
PURPOSE

Abbreviated as ScCms
AVAILABLE ON
c64 c64reu plus4 vic20

762
 15.467 SCREEN HEIGHT (constant)

15.467 SCREEN HEIGHT (constant)

SYNTAX
= SCREEN HEIGHT

PURPOSE
The SCREEN HEIGHT constant represents the actual height of the screen,
for the current video chipset and graphic / text mode, in terms of pixels.

Alias for HEIGHT (constant)

Abbreviated as ScHg
EXAMPLES
1 IF SCREEN HEIGHT > 128 THEN : PRINT " At least 128 pixels !!":
ENDIF

763
 15 Keywords

15.468 SCREEN HORIZONTAL SCROLL

SYNTAX
SCREEN HORIZONTAL SCROLL [integer]
SCREEN HORIZONTAL SCROLL [expression]

PURPOSE
Performs an hardware scroll of the screen. The scroll is always in the
direction from right to left, so with a displacement of 0 the screen is
exactly as it would be without scrolling while with the value 7 you would
have a scroll of 7 pixels to the left.
Abbreviated as ScHzScl
AVAILABLE ON

c128 c64 coco coco3 d32 d64 mo5 pc128op to8 vic20
EXAMPLES
1 SCREEN HORIZONTAL SCROLL 3
2 SCREEN HORIZONTAL SCROLL ne w Di sp la c em en t

764
 15.469 SCREEN OFF

15.469 SCREEN OFF

SYNTAX
SCREEN OFF

PURPOSE
Turn off the screen.
Abbreviated as ScOf

AVAILABLE ON
c128 c64 c64reu plus4 vic20
EXAMPLES
1 SCREEN OFF

765
 15 Keywords

15.470 SCREEN ON

SYNTAX
SCREEN ON

PURPOSE
Turn on the screen.
Abbreviated as ScON

AVAILABLE ON
c128 c64 c64reu plus4 vic20
EXAMPLES
1 SCREEN ON

766
 15.471 SCREEN PAGE

15.471 SCREEN PAGE

SYNTAX
= SCREEN PAGE

PURPOSE
The semantics of this keyword is different, depending on whether double
buffering is enabled or not. If double buffering is enabled, the SCREEN
PAGE function allows to know which page the program is on. There are
two pages, page 0 (PAGE 0 or PAGE A) and page 1 (PAGE 1 or PAGE
B). When you draw on page 0, page 1 is visible, and vice versa.
On the other hand, if doube buffering is not enabled, this function will
return the actual screen page in use, as set by SCREEN PAGE command.

Abbreviated as ScPg
AVAILABLE ON
coco3
EXAMPLES
1 IF SCREEN PAGE = PAGE 0 THEN
2 PRINT " first page "
3 ENDIF

767
 15 Keywords

15.472 SCREEN ROWS (constant)

SYNTAX
= SCREEN ROWS

PURPOSE
Alias for SCREEN TILES HEIGHT.
Alias for SCREEN TILES HEIGHT (constant), TILES HEIGHT (constant)

Abbreviated as ScRws
EXAMPLES
1 IF SCREEN ROWS > 10 THEN : PRINT " At least 10 rows !!": ENDIF

768
 15.473 SCREEN ROWS (instruction)

15.473 SCREEN ROWS (instruction)

SYNTAX
SCREEN ROWS rows

PURPOSE
Changes the number of lines that can be displayed. Depending on the
hardware, the effect can be different as different are the acceptable
values.

Abbreviated as ScRws
AVAILABLE ON
c128 c64 c64reu plus4 vic20

EXAMPLES
1 SCREEN ROWS 24

769
15 Keywords

15.474 SCREEN SHADES (constant)

SYNTAX
= SCREEN SHADES

PURPOSE
Alias for SHADES.
Alias for SHADES (constant)

See also COLOR, RGB

Abbreviated as ScShs

770
 15.475 SCREEN SPRITE RATIO X (constant)

15.475 SCREEN SPRITE RATIO X

(constant)

SYNTAX
= SCREEN SPRITE RATIO X

PURPOSE
This constant allows you to know the ratio (percentile) between the
screen reference system and the sprite reference system. In other words,
given a coordinate according to the screen reference system, you can
calculate the one according to the sprite reference system with the
following proportion:
( SCREEN WIDTH * SCREEN SPRITE RATIO X ) / 100

Abbreviated as ScSprRaX

771
15 Keywords

15.476 SCREEN SPRITE RATIO Y

(constant)

SYNTAX
= SCREEN SPRITE RATIO Y

PURPOSE
This constant allows you to know the ratio (percentile) between the
screen reference system and the sprite reference system. In other words,
given a coordinate according to the screen reference system, you can
calculate the one according to the sprite reference system with the
following proportion:
( SCREEN HEIGHT * SCREEN SPRITE RATIO Y ) / 100

Abbreviated as ScSprRaY

772
 15.477 SCREEN SWAP

15.477 SCREEN SWAP

SYNTAX
PURPOSE

Abbreviated as ScSwp

773
 15 Keywords

15.478 SCREEN TILES HEIGHT (constant)

SYNTAX
= SCREEN TILES HEIGHT

PURPOSE
The SCREEN TILES HEIGHT constant represents the actual width of
the screen, for the current video chipset and graphic / text mode, in
terms of tiles (characters).

Alias for TILES HEIGHT (constant), SCREEN COLUMNS (constant)

Abbreviated as ScTlsHg
EXAMPLES
1 IF SCREEN TILES HEIGHT > 10 THEN : PRINT " At least 10 rows !!":
ENDIF

774
 15.479 SCREEN TILES WIDTH (constant)

15.479 SCREEN TILES WIDTH (constant)

SYNTAX
= SCREEN TILES WIDTH

PURPOSE
The SCREEN TILES WIDTH constant represents the actual width of the
screen, for the current video chipset and graphic / text mode, in terms
of tiles (characters).

Alias for TILES WIDTH (constant), SCREEN COLUMNS (constant)

Abbreviated as ScTlsWd
EXAMPLES
1 IF SCREEN TILES WIDTH > 40 THEN : PRINT " At least 40 columns
!!": ENDIF

775
 15 Keywords

15.480 SCREEN VERTICAL SCROLL

SYNTAX
SCREEN VERTICAL SCROLL [integer]
SCREEN VERTICAL SCROLL [expression]

PURPOSE
Performs an hardware scroll of the screen. The scroll is always in the
direction from bottom to up, so with a displacement of 0 the screen
is exactly as it would be without scrolling while with the value 7 you
would have a scroll of 7 pixels upwards.
Abbreviated as ScVeScl
AVAILABLE ON

c128 c64 coco coco3 d32 d64 mo5 pc128op plus4 to8 vic20
EXAMPLES
1 SCREEN VERTICAL SCROLL 3
2 SCREEN VERTICAL SCROLL newScrolling

776
 15.481 SCREEN WIDTH (constant)

15.481 SCREEN WIDTH (constant)

SYNTAX
= SCREEN WIDTH

PURPOSE
The SCREEN WIDTH constant represents the actual width of the screen,
for the current video chipset and graphic / text mode, in terms of pixels.

Alias for WIDTH (constant)

Abbreviated as ScWd
EXAMPLES
1 IF SCREEN WIDTH > 128 THEN : PRINT " At least 128 pixels !!":
ENDIF

777
15 Keywords

15.482 SELECT CASE...CASE...CASE

ELSE...ENDSELECT

SYNTAX

SELECT CASE expression

CASE value1:
...
CASE value2:
...
...
[ CASE ELSE ]
...
ENDSELECT

PURPOSE

The SELECT CASE command is part of the SELECT CASE...END SELECT

structure. It allows you to execute different blocks of code depending
on the value of a variable or expression. In practice, it is like having a
series of ”cases” and the program executes the code corresponding to
the case that occurs.

The expression is evaluated at the beginning of the control block,

and its value is compared to the values specified in the cases. Each
CASE represents a possible value or a range of values of the expression.
Inside each case, you insert the instructions that will be executed if the
value of the expression matches that case. The CASE ELSE is optional,
and it is executed if no previous case is true. In 8-bit computers, the
semantics of SELECT CASE are closely tied to data representation. Be-
cause registers and variables were often limited to 8 bits, the values
that could be compared in cases are integers between 0 and 255, also
if ugBASIC supports any integer type Anyway, it allows the expression
to be compared to any integer value but, due to the 8-bit limitation,

778
 15.482 SELECT CASE...CASE...CASE ELSE...ENDSELECT

the range of values that could be compared should be limited, to be

effective, in terms of performances.
Using SELECT CASE makes code clearer and easier to understand than
a series of nested IF...THEN...ELSE statements. It can be more effi-
cient than a series of IF...THEN...ELSE statements.
See also CASE, CASE ELSE, ENDSELECT
Abbreviated as SlCsCsCsElEs
EXAMPLES
1 SELECT CASE number
2 CASE 1
3 PRINT " one !"
4 CASE 2
5 PRINT " two !"
6 CASE ELSE
7 PRINT " neither !"
8 ENDSELCT

779
 15 Keywords

15.483 SEND

SYNTAX
SEND data

PURPOSE
The SEND function send a character to DOJO connection.
Alias for DOJO SEND

Abbreviated as Sen
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 SEND " a "

780
 15.484 SEQUENCE (data type)

15.484 SEQUENCE (data type)

SYNTAX
... AS SEQUENCE

PURPOSE
The SEQUENCE data type maintains a reference to the collection of strips
of images that can be used to draw them on the screen.

Abbreviated as Seq

781
 15 Keywords

15.485 SET LINE

SYNTAX
SET LINE pattern

PURPOSE
The SET LINE statement changes the pattern used to draw lines.
Abbreviated as SeLn

EXAMPLES
1 SET LINE % 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0

782
 15.486 SET TAB

15.486 SET TAB

SYNTAX
SET TAB expression

PURPOSE
The SET TAB command specifies the number of characters that the text
cursor will move to the right when the next TAB$ is printed.

Abbreviated as SeTb
EXAMPLES
1 SET TAB 10

783
 15 Keywords

15.487 SGN

SYNTAX
= SGN(number)

PURPOSE
The SGN function is a very simple but useful mathematical function. Its
main function is to determine the sign of a number. In other words,
SGN tells you whether a number is positive, negative, or zero. So, it
returns 1 if number is positive, 0 if number is zero and -1 if number is
negative.
You can use SGN inside an IF condition to perform different actions
depending on the sign of a number, and in some cases, SGN can make
your code more concise and readable.

Abbreviated as Sg
EXAMPLES
1 x = SNG ( -42)

784
 15.488 SHADES (constant)

15.488 SHADES (constant)

SYNTAX
= SHADES

PURPOSE
This constant holds the maximum number of shades available for the
target, for the current mode. Note that, although this is the number
of shades available, it is not guaranteed that every single graphic or
text element in the mode could assume this value, independently. This
depends on the specific characteristics of the video chipset available.
Alias for SCREEN SHADES (constant)
See also COLOR, RGB

Abbreviated as Shs

785
 15 Keywords

15.489 SHARED

SYNTAX
SHARED var1[, var2[, ...] ]
SHARED "string1"[, "string2"[, ...] ]

PURPOSE
This keyword sets up a list of variables of a procedure that can be
accessed from absolutely anywhere in your program.

There is a facility of using strings in procedure definitions. As with

disc names, the ”wild card” characters * and ? can also be included.
In this case, the * character is used to mean ”match this with any
list of characters in the variable name, until the next control character
is reached”, and the ? character means ”match this with any single
character in the variable name”.
GLOBAL or SHARED should be employed before the first use of the vari-
able. Only strings may be used for this technique.
Abbreviated as Sr

EXAMPLES
1 SHARED test
2 SHARED " a *" , b , "* c "

786
 15.490 SHARED CONST

15.490 SHARED CONST

SYNTAX
[POSITIVE] SHARED CONST identifier = value
SHARED CONST identifier IN (min,max) = value
SHARED CONST identifier IN "[" min,max) = value
SHARED CONST identifier IN (min,max "]" = value
SHARED CONST identifier IN "[" min,max "]"" = value

PURPOSE
Alias for SHARED, CONST SHARED, GLOBAL CONST, CONST GLOBAL
Abbreviated as SrC#
EXAMPLES
1 SHARED CONST x = 42
2 POSITIVE SHARED CONST y = -42: ’ this raises an error !
3 SHARED CONST width IN (0 ,320] = 128

787
15 Keywords

15.491 SHIFT RIGHT (constant)

SYNTAX
= SHIFT RIGHT

PURPOSE
This constant represent the right ”SHIFT” key, when used as bitmask
for KEY SHIFT instruction.

Alias for RIGHT SHIFT (constant)

Abbreviated as SHIFTRg

788
 15.492 SHOOT

15.492 SHOOT

SYNTAX
SHOOT ON #[channel]

PURPOSE
This command makes the computer emit an shoot-like sound. It is
possible to indicate on which voices the system should emit the sound.
If omitted, it will be issued on all.

Abbreviated as Sho
AVAILABLE ON
atari c128 c128z c64 coleco cpc msx1 plus4

EXAMPLES
1 SHOOT
2 SHOOT ON %001

789
 15 Keywords

15.493 SIGNED BYTE (data type)

SYNTAX
... AS SIGNED BYTE

PURPOSE
The SIGNED BYTE represent the data type for 8 bit numbers with sign.
This kind of data can represent a relative number, integers between
-127 and 127 could be represented directly in a byte.

Abbreviated as SgndBy
EXAMPLES
1 DIM x AS SIGNED BYTE

790
 15.494 SIGNED DWORD (data type)

15.494 SIGNED DWORD (data type)

SYNTAX
... AS SIGNED DWORD

PURPOSE
The SIGNED DDWORD is a data type that allow to store a 32-bit word
(DWORD), with sign.

Alias for LONG (data type)

Abbreviated as Sgnd32BIT
EXAMPLES
1 DIM parolaLunga AS SIGNED DWORD

791
 15 Keywords

15.495 SIGNED WORD (data type)

SYNTAX
... AS SIGNED WORD

PURPOSE
The SIGNED WORD is a data type that allow to store a 16-bit word, with
sign.

Alias for INT (data type), INTEGER (data type)

Abbreviated as SgndWo
EXAMPLES
1 DIM parolaLunga AS SIGNED WORD

792
 15.496 SIN

15.496 SIN

SYNTAX
= SIN(angle)

PURPOSE
This function will calculate the sine value of an angle. The sine of
an acute angle are defined in the context of a right triangle: for the
specified angle, its sine is the ratio of the length of the side that is
opposite that angle to the length of the longest side of the triangle (the
hypotenuse), and the cosine is the ratio of the length of the adjacent
leg to that of the hypotenuse.
More generally, the definitions of sine can be extended to any real value
in terms of the lengths of certain line segments in a unit circle.

The sine functions are commonly used to model periodic phenomena

such as sound and light waves, the position and velocity of harmonic
oscillators, sunlight intensity and day length, and average temperature
variations throughout the year.

Abbreviated as Sn
EXAMPLES
1 x = SIN ( PI /2)

793
 15 Keywords

15.497 SIZE

SYNTAX
... = SIZE([resource])

PURPOSE
To get the (static) size of a buffer you can use the SIZE command.
This command will restore, in bytes, the size of the given buffer. It
is possible to apply this command to any type of static data, such as
BUFFER, IMAGE, IMAGES and constant strings.
Abbreviated as Sz
EXAMPLES
1 PRINT SIZE ( image )

794
 15.498 SLASH (constant)

15.498 SLASH (constant)

SYNTAX
= SLASH

PURPOSE
This constant represent the ”SLASH” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as SLASH
EXAMPLES
1 IF SCANCODE = SLASH THEN
2 PRINT " SLASH has been pressed !"
3 ENDIF

795
 15 Keywords

15.499 SOUND

SYNTAX
SOUND f1[,d1][;f1[,d2][;...]] [ON channels]

PURPOSE
The SOUND command add a touch of interactivity and liveliness to your
programs. Simply put, the SOUND command allows you to generate
sounds directly from your computer. You can give just the frequency
(to start an infinite sound) or a frequency followed by a duration. You
can play multiple sounds by concatenating frequencies or frequencies
and durations.
By combining several SOUND commands with different frequencies and
durations, you can compose short melodies. For example, you can make
a sound play when the user presses a button or reaches a goal in the
game. You can simulate the sounds of explosions, gunshots, or any
other effect you want.
This command allows you to handle multiple audio channels at the
same time, if the target has them, allowing you to create more complex
sounds. The waveform of the sound generated can vary depending on
the available hardware.

Abbreviated as So
AVAILABLE ON
atari atarixl c128 c64 c64reu coleco cpc msx1 plus4 sc3000
sg1000 vic20

EXAMPLES
1 SOUND #440
2 SOUND la ; do ; mi ; sol
3 SOUND #440 , #250 ON #%001

796
 15.500 SOUND OFF

15.500 SOUND OFF

SYNTAX
SOUND OFF ON [channels]

PURPOSE
The SOUND OFF command can be used to stop play a sound on a channel
or on all channels.

Abbreviated as SoOf
AVAILABLE ON
atari atarixl c128 c64 c64reu coleco cpc msx1 plus4 sc3000
sg1000 vic20

EXAMPLES
1 SOUND OFF
2 SOUND OFF ON primaVoce

797
 15 Keywords

15.501 SPACE (constant)

SYNTAX
= SPACE

PURPOSE
This constant represent the ”SPACE” key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Abbreviated as Sp
EXAMPLES
1 IF SCANCODE = SPACE THEN
2 PRINT " SPACE has been pressed !"
3 ENDIF

798
 15.502 SPACE (function)

15.502 SPACE (function)

SYNTAX
= SPACE(number)

PURPOSE
The SPACE command is used to generate a string of a specified number
of white spaces. This string can then be used in various operations,
such as formatting text, creating spacing, or aligning data within a line.

The SPACE command has many applications: you can use it to create
margins, indentations, or to align text precisely. By combining SPACE
with other commands, you can build simple tables with aligned columns.
You can also usethe SPACE to add or remove spaces from an existing
string.

Abbreviated as Sp
EXAMPLES
1 y = 42: x = SPACE ( y )

799
 15 Keywords

15.503 SPAWN

SYNTAX
[HALTED] SPAWN [identifier]

PURPOSE
This keyword will invoke a (parallel) procedure. The procedure can
be invoked in an ”halted” state using the keyword HALTED, so that a
RESPAWN command must be issued in order to ”wake up” the procedure.

Abbreviated as Sw
EXAMPLES
1 handle = SPAWN moveShip
2 handle = HALTED SPAWN moveArrow

800
 15.504 SPC

15.504 SPC

SYNTAX
PRINT SPC(spaces)

PURPOSE
The function SPC can be used to set a number of spaces, which are
printed onto screen. SPC can be used several times in a sentence.

Also note that SPC will not overwrite and erase things already printed on
screen, so PRINT SPC(3) is not the same as PRINT" " in that respect.
Abbreviated as Ss
EXAMPLES
1 PRINT SPC (10) ;"*"

801
15 Keywords

15.505 SPRITE (data type)

SYNTAX
DIM x AS SPRITE: x = SPRITE(xImage)

PURPOSE
This data type allows you to identify and use a hardware sprite resource.
Its value is not directly usable by the programmer, who must consider
the variable that contains it as a ”placeholder” for the sprite. Further-
more, this data type is used by both native hardware sprites (SPRITE)
and ”composite” ones (CSPRITE), but it is not possible to mix their
use.
Abbreviated as Spr

802
 15.506 SPRITE (function)

15.506 SPRITE (function)

SYNTAX
= SPRITE( resource ) flags
= SPRITE( resource, old ) flags

PURPOSE
This function can be used to define a hardware sprite. The first pa-
rameter must be a monochrome graphics resource, while the second
parameter (optional) can be the identifier of an already defined sprite.
If the second parameter is omitted, the sprite will be created using a
new identifier.
A sprite declaration can be followed by one or more optional flags that
serve to better describe the desired characteristics of the sprite.

With the MULTICOLOR flag you can indicate that the sprite is defined
by more than one color. Depending on the video chipset considered,
this can mean up to 4 colors instead of the single color. The opposite
is given by the MONOCOLOR flag, which defines a monochrome sprite.

The EXPAND VERTICAL flag allows you to increase the height of the
sprite and, depending on the video chipset considered, each pixel of the
sprite will be drawn with more pixels on the screen. The opposite is
obtained with the COMPRESS VERTICAL flag.
The EXPAND HORIZONTAL flag allows you to increase the width of the
sprite and, depending on the video chipset considered, each pixel of the
sprite will be drawn with more pixels on the screen. The opposite is
obtained with the COMPRESS HORIZONTAL flag.
The last flag is IGNORE COLOR, which allows you to indicate the color
to be considered as transparency (that is: ignored).

803
 15 Keywords

Please note that defining a sprite allows you to change its appearance
dynamically, and therefore allows you to perform (for example) ani-
mations. This redefinition should be understood as synchronous, and
therefore the program should be written to ensure the appropriate tim-
ing, in order to avoid flickering.
See also SPRITE
Abbreviated as Spr
AVAILABLE ON

c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 ship = SPRITE ( imageShip ) IGNORE BLACK

804
 15.507 SPRITE (instruction)

15.507 SPRITE (instruction)

SYNTAX
SPRITE index command1 [command2 [command3 ...]]
SPRITE command1 [command2 [command3 ...]]

PURPOSE
The SPRITE instructions can be used to prefix one or more commands
on specific hardware sprites. Commands can be specified, one after the
other, after specifying which sprite to refer to. If the sprite number
is omitted, it is assumed that the operations will be performed on all
hardware sprites.
See also SPRITE (function), SPRITE AT (command), SPRITE COLOR
(command), SPRITE COMPRESS HORIZONTAL (command), SPRITE COMPRESS
VERTICAL (command), SPRITE DISABLE (command), SPRITE ENABLE
(command), SPRITE EXPAND HORIZONTAL (command), SPRITE EXPAND
VERTICAL (command), SPRITE MONOCOLOR (command), SPRITE MULTICOLOR
(command)
Abbreviated as Spr

AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE 1 ENABLE MULTICOLOR
2 SPRITE ON

805
15 Keywords

15.508 SPRITE AT (command)

SYNTAX
SPRITE index AT (x1, y1) [command [command ...]]

PURPOSE
With the SPRITE AT action you can indicate the position where the
sprite will be placed. The positioning will happen instantly, and the
sprite will be drawn in that position as soon as the video raster line
reaches that position. Note that the position is indicated in sprites
coordinates, and not in pixels: it follows that it is necessary to carry out
the appropriate proportions using the constants (percentiles) SCREEN
SPRITE RATIO X and SCREEN SPRITE RATIO Y.
Additionally, the video screen may have a border around the area ac-
tually accessible to the graphics chipset: as a result, a hardware sprite
positioned with a coordinate that falls within the border may not be
visible. To remedy this problem, and ensure that the sprite is visible, it
is necessary to start from the positions induced by the SCREEN BORDER
X and SCREEN BORDER Y coordinates.

Finally, please note that the keyword to use is only AT, which must
therefore be prefixed by the SPRITE keyword and the sprite index. It
is possible to juxtapose multiple AT instructions but, obviously, the
processor speed is such that only the last one that counts will be the
one that counts.

See also SPRITE (function), SPRITE

Abbreviated as SprAt
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000

806
 15.508 SPRITE AT (command)

EXAMPLES
1 SPRITE #1 AT ( #100 , #100 )

807
 15 Keywords

15.509 SPRITE COLOR (command)

SYNTAX
SPRITE index COLOR color1 [command [command ...]]

PURPOSE
With the SPRITE COLOR command you can indicate the specific color
in which the sprite will be drawn. The color is specific to this sprite,
and different from the (possible) colors shared by all sprites, which can
be changed by the COLOR SPRITE command.
Note that the keyword to use is only COLOR, which must therefore be
preceded by the SPRITE keyword and the sprite index. It is possible to
put multiple COLOR instructions side by side, but obviously the processor
speed is such that only the last one will be the one that counts.

See also SPRITE (function), SPRITE, COLOR SPRITE

Abbreviated as SprCr
AVAILABLE ON

c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 SPRITE ship COLOR WHITE

808
 15.510 SPRITE COMPRESS HORIZONTAL (command)

15.510 SPRITE COMPRESS

HORIZONTAL (command)

SYNTAX
SPRITE index COMPRESS HORIZONTAL [command [command ...]]

PURPOSE
With the SPRITE COMPRESS HORIZONTAL command you can compress
the sprite horizontally, so that it is effectively one pixel on the screen
for every pixel of the sprite.

Note that the keyword to use is only COMPRESS HORIZONTAL, which

must therefore be preceded by the keyword SPRITE and the sprite index.
You can put multiple COMPRESS HORIZONTAL statements together, but
of course this will have no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprCprHz
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship COMPRESS HORIZONTAL

809
 15 Keywords

15.511 SPRITE COMPRESS VERTICAL

(command)

SYNTAX
SPRITE index COMPRESS VERTICAL [command [command ...]]

PURPOSE
With the SPRITE COMPRESS VERTICAL command you can compress
the sprite horizontally, so that it is effectively one pixel on the screen
for every pixel of the sprite.

Note that the keyword to use is only COMPRESS VERTICAL, which must
therefore be preceded by the keyword SPRITE and the sprite index.
You can put multiple COMPRESS VERTICAL statements together, but of
course this will have no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprCprVe
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship COMPRESS VERTICAL

810
 15.512 SPRITE COUNT (constant)

15.512 SPRITE COUNT (constant)

SYNTAX
= SPRITE COUNT

PURPOSE
This constant allows you to know the number of hardware sprites avail-
able on the target considered. Note that this is the effective limit
allowed by the video chipset: however, ugBASIC can provide additional
mechanisms to multiply the number of available sprites, such as the
so-called ”sprite multiplexing”.
Abbreviated as SprC%

811
 15 Keywords

15.513 SPRITE DISABLE (command)

SYNTAX
SPRITE index DISABLE [command [command ...]]

PURPOSE
With the SPRITE DISABLE command you can disable (hide) the sprite,
so that it will not be drawn anymore.

Note that the keyword to use is only DISABLE, which must therefore
be preceded by the keyword SPRITE and the sprite index. You can put
multiple DISABLE statements together, but of course this will have no
effect.
See also SPRITE (function), SPRITE

Abbreviated as SprDx
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 SPRITE ship DISABLE

812
 15.514 SPRITE ENABLE (command)

15.514 SPRITE ENABLE (command)

SYNTAX
SPRITE index ENABLE [command [command ...]]

PURPOSE
With the SPRITE ENABLE command you can enable (show) the sprite,
so that it will be drawn.

Note that the keyword to use is only ENABLE, which must therefore be
preceded by the keyword SPRITE and the sprite index. You can put
multiple ENABLE statements together, but of course this will have no
effect.
See also SPRITE (function), SPRITE

Abbreviated as SprEn
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 SPRITE ship ENABLE

813
 15 Keywords

15.515 SPRITE EXPAND HORIZONTAL

(command)

SYNTAX
SPRITE index EXPAND HORIZONTAL [command [command ...]]

PURPOSE
With the SPRITE EXPAND HORIZONTAL command you can expand the
sprite horizontally, so that it is more than one pixel on the screen for
every pixel of the sprite.

Note that the keyword to use is only EXPAND HORIZONTAL, which must
therefore be preceded by the keyword SPRITE and the sprite index.
You can put multiple EXPAN HORIZONTAL statements together, but of
course this will have no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprExpHz
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship EXPAND HORIZONTAL

814
 15.516 SPRITE EXPAND VERTICAL (command)

15.516 SPRITE EXPAND VERTICAL

(command)

SYNTAX
SPRITE index EXPAND VERTICAL [command [command ...]]

PURPOSE
With the SPRITE EXPAND VERTICAL command you can expand the
sprite horizontally, so that it is more than one pixel on the screen for
every pixel of the sprite.

Note that the keyword to use is only EXPAND VERTICAL, which must
therefore be preceded by the keyword SPRITE and the sprite index. You
can put multiple EXPAN VERTICAL statements together, but of course
this will have no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprExpVe
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship EXPAND VERTICAL

815
15 Keywords

15.517 SPRITE HEIGHT (constant)

SYNTAX
= SPRITE HEIGHT

PURPOSE
This constant allows you to know the height of hardware sprites available
on the target considered. Note that this is the effective limit allowed
by the video chipset: however, ugBASIC can provide additional mech-
anisms to increase the height of sprites, such as the so-called ”sprite
multiplexing”.
Abbreviated as SprHg

816
 15.518 SPRITE MAX X (constant)

15.518 SPRITE MAX X (constant)

SYNTAX
= SPRITE MAX X

PURPOSE
This constant allows us to know which is the largest abscissa (x) that can
assume the horizontal position of a sprite. It may or may not coincide
with the horizontal resolution of the screen, in the sense that some
graphics chipsets can move sprites far beyond what is representable
(example: border management on the VIC-II).
Abbreviated as SprMxX
EXAMPLES
1 maxX = SPRITE MAX X

817
 15 Keywords

15.519 SPRITE MAX Y (constant)

SYNTAX
= SPRITE MAX Y

PURPOSE
This constant allows us to know which is the largest ordinate (y) that
can assume the vertical position of a sprite. It may or may not coincide
with the horizontal resolution of the screen, in the sense that some
graphics chipsets can move sprites far beyond what is representable
(example: border management on the VIC-II).
Abbreviated as SprMxY
EXAMPLES
1 maxY = SPRITE MAX Y

818
 15.520 SPRITE MIN X (constant)

15.520 SPRITE MIN X (constant)

SYNTAX
= SPRITE MIN X

PURPOSE
This constant allows us to know which is the smallest abscissa (x)
that can assume the horizontal position of a sprite. It may or may
not coincide with zero of the screen, in the sense that some graphics
chipsets can move sprites far beyond what is representable (example:
border management on the VIC-II).
Abbreviated as SprMnX
EXAMPLES
1 minX = SPRITE MIN X

819
 15 Keywords

15.521 SPRITE MIN Y (constant)

SYNTAX
= SPRITE MIN Y

PURPOSE
This constant allows us to know which is the smallest ordinate (y)
that can assume the vertical position of a sprite. It may or may not
coincide with zero of the screen, in the sense that some graphics chipsets
can move sprites far beyond what is representable (example: border
management on the VIC-II).
Abbreviated as SprMnY
EXAMPLES
1 minX = SPRITE MIN Y

820
 15.522 SPRITE MONOCOLOR (command)

15.522 SPRITE MONOCOLOR (command)

SYNTAX
SPRITE index MONOCOLOR [command [command ...]]

PURPOSE
With the SPRITE MONOCOLOR command you can set the sprite as monochrome.
Note that the keyword to use is only MONOCOLOR, which must therefore
be preceded by the keyword SPRITE and the sprite index. You can put
multiple MONOCOLOR statements together, but of course this will have
no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprMc
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship MONOCOLOR

821
 15 Keywords

15.523 SPRITE MULTICOLOR (command)

SYNTAX
SPRITE index MULTICOLOR [command [command ...]]

PURPOSE
With the SPRITE MULTICOLOR command you can set the sprite as poly-
chrome.

Note that the keyword to use is only MULTICOLOR, which must therefore
be preceded by the keyword SPRITE and the sprite index. You can put
multiple MULTICOLOR statements together, but of course this will have
no effect.
See also SPRITE (function), SPRITE

Abbreviated as SprMcs
AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000

EXAMPLES
1 SPRITE ship MULTICOLOR

822
 15.524 SPRITE OFF (command)

15.524 SPRITE OFF (command)

SYNTAX
SPRITE index OFF [command [command ...]]

PURPOSE
Alias for SPRITE DISABLE.
Abbreviated as SprOf

AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship OFF

823
 15 Keywords

15.525 SPRITE ON (command)

SYNTAX
SPRITE index ON [command [command ...]]

PURPOSE
Alias for SPRITE ENABLE.
Abbreviated as SprON

AVAILABLE ON
c128 c64 c64reu coleco msx1 sc3000 sg1000
EXAMPLES
1 SPRITE ship ON

824
 15.526 SPRITE WIDTH (constant)

15.526 SPRITE WIDTH (constant)

SYNTAX
= SPRITE WIDTH

PURPOSE
This constant allows you to know the width of hardware sprites available
on the target considered. Note that this is the effective limit allowed
by the video chipset: however, ugBASIC can provide additional mech-
anisms to increase the width of sprites, such as the so-called ”sprite
multiplexing”.
Abbreviated as SprWd

825
15 Keywords

15.527 SPRITE X MAX (constant)

SYNTAX
= SPRITE X MAX
= SPRITE MAX X

PURPOSE
This constant allows you to know the maximum value of horizontal
position of hardware sprites available on the target considered. Note
that this is the effective limit allowed by the video chipset.
Abbreviated as SprXMx

826
 15.528 SPRITE X MIN (constant)

15.528 SPRITE X MIN (constant)

SYNTAX
= SPRITE X MIN
= SPRITE MIN X

PURPOSE
This constant allows you to know the minimum value of horizontal
position of hardware sprites available on the target considered. Note
that this is the effective limit allowed by the video chipset.
Abbreviated as SprXMn

827
15 Keywords

15.529 SPRITE Y MAX (constant)

SYNTAX
= SPRITE Y MAX
= SPRITE MAX Y

PURPOSE
This constant allows you to know the maximum value of vertical position
of hardware sprites available on the target considered. Note that this is
the effective limit allowed by the video chipset.
Abbreviated as SprYMx

828
 15.530 SPRITE Y MIN (constant)

15.530 SPRITE Y MIN (constant)

SYNTAX
= SPRITE Y MIN
= SPRITE MIN Y

PURPOSE
This constant allows you to know the minimum value of vertical position
of hardware sprites available on the target considered. Note that this is
the effective limit allowed by the video chipset.
Abbreviated as SprYMn

829
 15 Keywords

15.531 SQR

SYNTAX
= SQR(expression)

PURPOSE
The SQR command (short for ”square root”) is a mathematical function
that is used to calculate the square root of a number. In other words,
given a number x, the command SQR(x) returns the number that, when
multiplied by itself, gives the result x.
The SQR command has many applications in programming: it is used
in any calculation that requires the calculation of the square root, such
as in the Pythagorean theorem. The square root is present in many
physics formulas, such as in the calculation of velocity. It is used also
to calculate the lengths of segments or areas of geometric figures, and
in many statistical calculations, such as in the calculation of standard
deviation.
The square root of a negative number is not defined in real numbers.
If you try to calculate the square root of a negative number, the result
is indefinite. Moreover, the function is defined in the integer numbers
domain.
EXAMPLES
1 PRINT SNG (81)

830
 15.532 STORAGE...ENDSTORAGE

15.532 STORAGE...ENDSTORAGE

SYNTAX
PURPOSE

To conclude the definition of a mass memory, the ENDSTORAGE com-

mand can be used.
Abbreviated as StrEns

831
 15 Keywords

15.533 STR

SYNTAX
= STR(number)

PURPOSE
This function converts numbers into strings. This can be used to over-
come some limitations posed by functions which does not accept num-
bers as parameters, but will work happily with parameters in the form
of strings. Also, when string adding is performed, all operand must be
strings, so this function is really useful.
EXAMPLES
1 x = STR (42)

832
 15.534 STRING (data type)

15.534 STRING (data type)

SYNTAX
... AS STRING

PURPOSE
The STRING data type maintains a reference to a static or dynamic
string.

Abbreviated as S1

833
 15 Keywords

15.535 STRING (function)

SYNTAX
= STRING( text, repetitions )

PURPOSE
The STRING function is used to create a string by repeating a single
character or substring a certain number of times. This is very useful for
creating fixed-length strings, such as borders, padding, or separators.

The STRING function has several applications: it can be used to create

borders for your tables or to delimit sections of text, and spaces to
align text or to create fixed-width columns. You can create lines of
special characters to separate different sections of an output, or a create
repeating patterns of characters.

Abbreviated as S1
EXAMPLES
1 x = STRING ( " A " , 42 )

834
 15.536 STRIP (storage)

15.536 STRIP (storage)

SYNTAX
STRIP source [AS target] FRAME SIZE (widh, height)

PURPOSE
The SEQUENCE command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
a sequence of images. The basic syntax requires indicating the name
of the source file that will be converted and inserted into the medium.
If you don’t want to use the same name, you can indicate an alias (AS
target).
Abbreviated as Sti

EXAMPLES
1 STRIP " examples / data . png " FRAME SIZE (32 , 32)
2 STRIP " sprites . bmp " AS " sprites . dat " FRAME SIZE (32 , 32)

835
15 Keywords

15.537 STRIP LOAD

SYNTAX
PURPOSE

Alias for LOAD SEQUENCE

Abbreviated as StiLd

836
 15.538 STRPTR

15.538 STRPTR

SYNTAX
= STRPTR(var)

PURPOSE
This function allows you to retrieves the address in memory where the
actual text of a given string is located.

Abbreviated as Spt
EXAMPLES
1 address = STRPTR ( x )

837
 15 Keywords

15.539 SUCCESS

SYNTAX
= SUCCESS( )

PURPOSE
The SUCCESS function will return TRUE if the last DOJO command has
been successfully executed.

Alias for DOJO SUCCESS

Abbreviated as Su
AVAILABLE ON
c64 c64reu coco coco3

EXAMPLES
1 IF SUCCESS ( ) THEN PRINT " ok !"

838
 15.540 SWAP

15.540 SWAP

SYNTAX
SWAP var1, var2

PURPOSE
The SWAP command is used to swap the values of two variables. In
practice, the contents of the first variable are assigned to the second
and vice versa, in a single operation.

The SWAP command makes code more concise and readable by avoiding
the use of a temporary variable for swapping. Since swapping elements
is a fundamental operation in many sorting algorithms, such as bubble
sort, it is important that it is an efficient operation. Infact, actually
performs a similar operation at the assembly level, more efficiently and
hidden from the programmer.
The SWAP operation can only be used with variables of the same bit
width (in case of numeric type) or the same type (if strings).
See also AT

Abbreviated as Swp
EXAMPLES
1 a = 42 : b = 84
2 AT a , b
3 PRINT a , b

839
 15 Keywords

15.541 SYS

SYNTAX
SYS address
[ WITH REG(r1)=v1[, REG(r2)=v2 [, ... ] ] ]
[ RETURN x1=REG(r1)[, x2=REG(r2)[, ... ] ] ]
[ ON target1[, target2[, ... ] ] ]

PURPOSE

This command allows you to start the execution of a subroutine, written

directly in machine language, starting from the indicated address. It
must be noted that this jump is intended as a return: any assembly
instruction that returns from execution will continue the execution of
the program from the next ugBASIC line.

Moreover, it is possible to communicate with the machine code. This is

made possible by indicating, at the same time as the call, the population
of specific input registers and the recovery of values from specific output
registers.
The extended syntax allow the specification of r1, r2, .. as the various
processor registers, v1, v2, .. are the values passed in the various
registers and x1, x2, .. are the variables that will receive the execution
result from the various registers. Since the registers are different from
CPU to CPU, it can be useful to add the ON target specification.
See also EXEC

Abbreviated as Sy
EXAMPLES
1 SYS #49142
2 SYS indirizzo
3 SYS indirizzo WITH REG ( A ) =42 RETURN y = REG ( B ) ON CPUZ80

840
 15.542 TAB (constant)

15.542 TAB (constant)

SYNTAX
= TAB

PURPOSE
This constant represent the ”TAB” key, when used as a value to com-
pare with SCANCODE,KEY STATE and KEY PRESSED. If the key does not
exist in the corresponding target, the value will be zero.

Abbreviated as Tb
EXAMPLES
1 IF SCANCODE = TAB THEN
2 PRINT " TAB has been pressed !"
3 ENDIF

841
 15 Keywords

15.543 TAB$

SYNTAX

= TAB$

PURPOSE
The TAB$ function returns a special control character called TAB, which
carries the ASCII code of 9. When this character is printed, the text
cursor is automatically moved to the next tabulated column setting
(tab) to the right. The default setting for this is four characters, which
can be changed using SET TAB.
EXAMPLES
1 PRINT TAB$

842
 15.544 TAN (constant)

15.544 TAN (constant)

SYNTAX
= TAN

PURPOSE
This keyword represents the color tan. Depending on the methodology
and technique, as well as the available hardware, it can correspond to a
specific color in the RGB space. However, not all computers have this
color. In which case, it is approximated by the closest color available,
which is usually also used in decoding images to identify the color to
use.
Abbreviated as Tn

EXAMPLES
1 PEN TAN

843
 15 Keywords

15.545 TAN (function)

SYNTAX
= TAN(angle)

PURPOSE
This function will calculate the tangent value of an angle. It is the ratio
of the opposite side and the adjacent side of the angle in consideration
in a right-angled triangle.

Abbreviated as Tn
EXAMPLES
1 x = TAN (0)

844
 15.546 TASK (data type)

15.546 TASK (data type)

SYNTAX
... AS TASK

PURPOSE
The TASK data type holds a reference to a thread created with SPAWN
command.

Alias for THREAD

Abbreviated as Ts

845
15 Keywords

15.547 TEXT

SYNTAX
TEXT [AT] x, y, string

PURPOSE
The TEXT command allows you to write text at a certain position on
the screen.

See also LOCATE, PRINT

Abbreviated as Tx

846
 15.548 TEXTADDRESS

15.548 TEXTADDRESS

SYNTAX
[variable] = TEXTADDRESS
TEXTADDRESS = [expression]
= TEXTADDRESS
TEXTADDRESS = ...

PURPOSE

This is a variable (16 bit) that contains the actual address of the
textmap. It can be modified directly by using assignment, and can
be read as any other variable. Note that no check is done when using
this variable, so an invalid value lead to undefined behaviours. If you
want to use a valid value please use the [[TEXTMAP AT]] command.

This is a variable (16 bit) that contains the actual address of the
textmap. It can be modified directly by using assignment, and can
be read as any other variable. Note that no check is done when using
this variable, so an invalid value lead to undefined behaviours. If you
want to use a valid value please use the TEXTMAP AT command.

See also TEXTMAP AT

Abbreviated as Txa
AVAILABLE ON
c64 coco vic20

EXAMPLES
1 actual = TEXTADDRESS
2 TEXTADDRESS = $8400

847
 15 Keywords

15.549 TEXTMAP AT

SYNTAX
TEXTMAP AT [expression]

PURPOSE
Abbreviated as TxmAt
AVAILABLE ON

c64 coco d32 d64 mo5 vic20

EXAMPLES
1 TEXTMAP AT n e w T e x t m a p A d d r e s s

848
 15.550 THREAD (data type)

15.550 THREAD (data type)

SYNTAX
... AS THREAD

PURPOSE
The THREAD data type holds a reference to a thread created with SPAWN
command.

Alias for TASK

Abbreviated as Thr

849
15 Keywords

15.551 TI

SYNTAX
PURPOSE

Alias for TIMER

850
 15.552 TICK PER SECOND

15.552 TICK PER SECOND

SYNTAX
= TICK PER SECOND

PURPOSE
This constant holds the number of ticks that occur each second.
Abbreviated as TkPexSec

851
 15 Keywords

15.553 TICKS PER SECOND

SYNTAX
= TICKS PER SECOND

PURPOSE
The TICKS PER SECOND returns the number of ticks per second that
can be detected using the TIMER keyword. Note that this value is
calculated dynamically at the start of the program, and is therefore no
longer modified. However, because there may be versions of the same
hardware running at different frequencies, the value cannot be used as
a compile-time constant.
Abbreviated as TksPexSec

EXAMPLES
1 PRINT TICKS PER SECOND

852
 15.554 TILE AT

15.554 TILE AT

SYNTAX
= TILE AT([x],[y])

PURPOSE
This function allows you to know which is the tile drawn at a certain
position on the tilemap. Since it is possible to draw both single TILE
and TILES, the information on the drawn tile is not, automatically, the
identifier of a TILES but it is the single tile of which it is formed. To
know if the tile belongs to a group of tiles it is necessary to use the
TILES BELONG function.
Abbreviated as TlAt

AVAILABLE ON
atari c128 c128z c64 coco coco3 coleco cpc d32 d64 plus4
sc3000 sg1000 vic20
EXAMPLES
1 tile = TILE AT ( 10 ,10 )

853
 15 Keywords

15.555 TILE BELONG TO

SYNTAX
= TILE tile BELONG TO tiles

PURPOSE
The TILE ... BELONG TO ... command allows you to check if a
certain TILE belongs to the set of tiles that make up a TILES. In general,
TILES are made up of multiple simple tiles and, when drawn, actually
occupy multiple tiles. This command allows you to make distinctions.
Abbreviated as TlBnTo
EXAMPLES
1 = TILE tile BELONG TO multitiles

854
 15.556 TILE CLASS

15.556 TILE CLASS

SYNTAX
= TILE CLASS(tileset, id)

PURPOSE
This function allows you to know the class to which a certain tile be-
longs. Note that this information is available only at the time of com-
pilation: therefore, the parameter with the tile identifier must be a
constant.
Abbreviated as TlCss
EXAMPLES
1 tileClass = TILE CLASS ( tileset , 29)

855
 15 Keywords

15.557 TILE FIRST

SYNTAX
= TILE FIRST([tiles])

PURPOSE
This function allows you to obtain the first TILE of a given set of TILES
Abbreviated as TlFST

AVAILABLE ON
atari c128 c128z c64 coleco cpc d64 mo5 msx1 pc128op plus4
sc3000 sg1000 to8 vg5000 vic20 zx
EXAMPLES
1 firstTile = TILE FIRST ( LOAD TILES (" starship . png ") )

856
 15.558 TILE HEIGHT

15.558 TILE HEIGHT

SYNTAX
= TILE HEIGHT([tile])
= TILE HEIGHT([tileset])

PURPOSE
This function allows you to obtain the height of a given TILE or a given
set of TILES. The width is expressed in tiles. If the parameter is a
“TILESET“, this is the height of a single tile.
Abbreviated as TlHg
EXAMPLES
1 starshipHeight = TILE HEIGHT ( LOAD TILE (" starship . png ") )
2 singleTileHeig h t = TILE HEIGHT ( LOAD TILESET (" tileset . tsx ") )

857
 15 Keywords

15.559 TILE ID

SYNTAX
= TILE ID(tileset, name)

PURPOSE
This function allows you retrieve the (numeric) identification, given the
symbolic name of the tile. Note that this information is available only at
the time of compilation: therefore, the parameter with the tile identifier
must be a constant.
Abbreviated as TlId
EXAMPLES
1 myTile = TILE ID ( tileset , name_my_tile )

858
 15.560 TILE LOAD

15.560 TILE LOAD

SYNTAX
PURPOSE

Alias for LOAD TILE

Abbreviated as TlLd

859
 15 Keywords

15.561 TILE PROBABILITY

SYNTAX
= TILE PROBABILITY( tileset, id )

PURPOSE
This function allows you to know the probability to which a certain tile
will be produced. Note that this information is available only at the
time of compilation: therefore, the parameter with the tile identifier
must be a constant.
Abbreviated as TlPROBABILITY
EXAMPLES
1 tileProb ab il i ty = TILE PROBABILITY ( tileset , 29)

860
 15.562 TILE WIDTH

15.562 TILE WIDTH

SYNTAX
= TILE WIDTH([tile])
= TILE WIDTH([tileset])

PURPOSE
This function allows you to obtain the width of a given TILE or a given
set of TILES. The width is expressed in tiles. If the parameter is a
“TILESET“, this is the width of a single tile.
Abbreviated as TlWd
EXAMPLES
1 starshipWidth = TILE WIDTH ( LOAD TILE (" starship . png ") )
2 singleTileWidth = TILE WIDTH ( LOAD TILESET (" tileset . tsx ") )

861
 15 Keywords

15.563 TILEMAP (constant)

SYNTAX
... = TILEMAP

PURPOSE
This is the bitmask used to select the TILE mode.
See also BITMAP (constant)

Abbreviated as Tm
EXAMPLES
1 IF SCREEN IS TILEMAP THEN : PRINT " tilemap is native !": ENDIF

862
 15.564 TILEMAP (storage)

15.564 TILEMAP (storage)

SYNTAX
TILEMAP source [AS target]

PURPOSE
The TILEMAP command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
a tilemap. The basic syntax requires indicating the name of the source
file that will be converted and inserted into the medium. If you don’t
want to use the same name, you can indicate an alias (AS target).
Abbreviated as Tm
EXAMPLES
1 TILEMAP " dungeon . tmx " AS " dungeon "

863
 15 Keywords

15.565 TILEMAP AT

SYNTAX
= TILEMAP [LAYER layer] map AT([x],[y])

PURPOSE
This function allows to know which is the tile present in a tilemap,
given the coordinates of the tile itself. If the tilemap has more than one
layer, the first layer will be returned. If you need to retrieve the tile of a
different level, you have to indicate the layer with the LAYER keyword.
Abbreviated as TmAt
EXAMPLES
1 tile = TILEMAP map AT (0 ,0)
2 tile = TILEMAP map LAYER 2 AT (0 ,0)

864
 15.566 TILEMAP DISABLE

15.566 TILEMAP DISABLE

SYNTAX
TILEMAP DISABLE

PURPOSE
Disable the tilemap mode.
Abbreviated as TmDx

AVAILABLE ON
c64
EXAMPLES
1 TILEMAP DISABLE

865
 15 Keywords

15.567 TILEMAP ENABLE

SYNTAX
TILEMAP ENABLE

PURPOSE
Enable the tilemap mode.
Abbreviated as TmEn

AVAILABLE ON
atari c128 c128z c64 coleco cpc msx1 sc3000 sg1000 vg5000
vic20 zx
EXAMPLES
1 TILEMAP ENABLE

866
 15.568 TILEMAP HEIGHT

15.568 TILEMAP HEIGHT

SYNTAX
= TILEMAP HEIGHT(tilemap)

PURPOSE
This function allows you to obtain the height of a given TILEMAP. The
height is expressed in tiles

Abbreviated as TmHg
EXAMPLES
1 starshipHeight = TILEMAP HEIGHT ( tilemap )

867
 15 Keywords

15.569 TILEMAP INDEX

SYNTAX
= TILEMAP INDEX( column, row [, layer] )

PURPOSE
The TILEMAP INDEX allows you to know the identifier of the tile located
in correspondence with the given set of coordinates. In particular, given
a tile map as parameter, you can know what the tile is at the x, y
position and, if present and given, at the given layer.
See also TILEMAP TILE AT
Abbreviated as TmIdx

EXAMPLES
1 index = TILEMAP INDEX ( 0 , 0 )
2 index = TILEMAP INDEX ( 0 , 0 , 1 )

868
 15.570 TILEMAP TILE AT

15.570 TILEMAP TILE AT

SYNTAX
= TILEMAP TILE AT( column, row [, layer] )

PURPOSE
Alias for TILEMAP INDEX
Abbreviated as TmTlAt

EXAMPLES
1 index = TILEMAP TILE AT ( 0 , 0 )
2 index = TILEMAP TILE AT ( 0 , 0 , 1 )

869
 15 Keywords

15.571 TILEMAP WIDTH

SYNTAX
= TILEMAP WIDTH(tilemap)

PURPOSE
This function allows you to obtain the width of a given TILEMAP. The
width is expressed in tiles

Abbreviated as TmWd
EXAMPLES
1 w = TILEMAP WIDTH ( tilemap )

870
 15.572 TILES AT

15.572 TILES AT

SYNTAX
TILES AT # [integer]
TILES AT [expression]

PURPOSE
Set the starting address, in memory, for the tiles (for textual mode).
The input parameter is decoded and declined according to the hardware
limits. So it is not said that exactly the given address is set.
Abbreviated as TlsAt
AVAILABLE ON

c128 c64 vic20

EXAMPLES
1 TILES AT # $8400
2 TILES AT tilesAddress

871
 15 Keywords

15.573 TILES HEIGHT (constant)

SYNTAX
= TILES HEIGHT

PURPOSE
Alias for SCREEN TILES HEIGHT.
Alias for SCREEN TILES HEIGHT (constant), SCREEN COLUMNS (constant)

Abbreviated as TlsHg
EXAMPLES
1 IF TILES HEIGHT > 10 THEN : PRINT " At least 10 rows !!": ENDIF

872
 15.574 TILES LOAD

15.574 TILES LOAD

SYNTAX
PURPOSE

Alias for LOAD TILES, FONT LOAD

Abbreviated as TlsLd

873
 15 Keywords

15.575 TILES WIDTH (constant)

SYNTAX
= TILES WIDTH

PURPOSE
Alias for SCREEN TILES WIDTH.
Alias for SCREEN TILES WIDTH (constant), SCREEN COLUMNS (constant)

Abbreviated as TlsWd
EXAMPLES
1 IF TILES WIDTH > 40 THEN : PRINT " At least 40 columns !!": ENDIF

874
 15.576 TILESET (storage)

15.576 TILESET (storage)

SYNTAX
TILESET source [AS dest]

PURPOSE
The TILESET command, inserted inside a BEGIN STORAGE - ENDSTORAGE
block, allows you to define the content of the mass storage element as
a tileset. The basic syntax requires indicating the name of the source
file that will be converted and inserted into the medium. If you don’t
want to use the same name, you can indicate an alias (AS target).
Abbreviated as Tse
EXAMPLES
1 TILESET " tiles . tsx " AS " tiles "

875
 15 Keywords

15.577 TILESET OF

SYNTAX
= TILESET OF [tilemap]

PURPOSE
This command allows you to obtain the TILESET of a given TILEMAP.
Abbreviated as TseOF

EXAMPLES
1 ts = TILESET OF map

876
 15.578 TIMER

15.578 TIMER

SYNTAX
= TIMER
TIMER = [50th/60th seconds]

PURPOSE
This variable represents a ”timer”, which is the number of sixtieths /
fiftieths of a second that have passed since the machine was turned
on. This variable, when used as a value, measures the elapsed time.
However, it can be set to an arbitrary value, such as 0, to measure a
defined period of time.
The refresh rate of this timer depends on the type of video standard
used, that is, PAL (50Hz) or NTSC (60Hz).

This variable can be abbreviated as TI.

See also TI
Abbreviated as Tmr

AVAILABLE ON
atari c128 c128z coco coco3 coleco cpc d32 d64 mo5 msx1 pc128op
plus4 sc3000 sg1000 to8 vg5000 vic20 zx
EXAMPLES
1 PRINT TIMER

877
 15 Keywords

15.579 TURQUOISE (constant)

SYNTAX
= TURQUOISE

PURPOSE
This keyword represents the color turquoise. Depending on the method-
ology and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space. However, not all computers have
this color. In which case, it is approximated by the closest color avail-
able, which is usually also used in decoding images to identify the color
to use.
Abbreviated as Tu

EXAMPLES
1 PEN TURQUOISE

878
 15.580 UBOUND

15.580 UBOUND

SYNTAX
= UBOUND( array [, dimension])

PURPOSE
The UBOUND command (short for ”upper bound”) is used to determine
the highest index of an array. In other words, it tells you how far up the
array goes.

Imagine you have a box of numbered chocolates. UBOUND tells you what
the number of the last chocolate is. This is useful when you need to
iterate over all the elements of an array, because it gives you the end
point of the loop.

UBOUND and LBOUND are often used together to define the bounds of a
FOR loop, and are complementary commands: they allow you to obtain
complete information about the structure of an array. Knowing these
two values, you can iterate over all the elements of the array, calculate
its total size, and perform many other operations.

Abbreviated as Ub
EXAMPLES
1 DIM a (10 ,20)
2 PRINT UBOUND (a ,1) : REM it will print 20

879
 15 Keywords

15.581 UCASE

SYNTAX
= UCASE(text)

PURPOSE
Alias for UPPER
Abbreviated as Uca

EXAMPLES
1 x = UCASE ( " ugBASIC " )

880
 15.582 UP (constant)

15.582 UP (constant)

SYNTAX
= UP

PURPOSE
This constant represent the ”UP” key, when used as a value to compare
with SCANCODE,KEY STATE and KEY PRESSED. If the key does not exist
in the corresponding target, the value will be zero.

Abbreviated as UP
EXAMPLES
1 IF KET STATE ( UP ) THEN
2 PRINT " UP has been pressed !"
3 ENDIF

881
 15 Keywords

15.583 UP ARROW (constant)

SYNTAX
= UP ARROW

PURPOSE
This constant represent the up arrow key, when used as a value to
compare with SCANCODE,KEY STATE and KEY PRESSED. If the key does
not exist in the corresponding target, the value will be zero.

Alias for ARROW UP (constant)

Abbreviated as UPAw
EXAMPLES
1 IF SCANCODE = UP ARROW THEN
2 PRINT " UP ARROW has been pressed !"
3 ENDIF

882
 15.584 UPPER

15.584 UPPER

SYNTAX
= UPPER(text)

PURPOSE
The UPPER command (short for ”Upper Case”) is a function that
converts all lowercase letters in a string to uppercase. In other words,
it takes any string and returns a new string that is identical to the first,
but with all letters in uppercase.
If you want to compare two strings without regard to case, you can
convert both strings to uppercase before performing the comparison.
You can use this command to standardize user input, for example to
ensure that all names are uppercase. You can use it to make the output
more readable or to conform to specific formatting conventions.
Alias for UCASE
Abbreviated as Up
EXAMPLES
1 x = UPPER ( " ugBASIC " )

883
 15 Keywords

15.585 USE TILESET

SYNTAX
USE TILESET tileset

PURPOSE
The USE TILESET command allows you to change the current active
tileset.

Abbreviated as UxTse
AVAILABLE ON
atari vg5000
EXAMPLES
1 USE TILESET schema1

884
 15.586 VAL

15.586 VAL

SYNTAX
= VAL(string)

PURPOSE
The VAL command is a function that allows you to convert a string
that represents a number into a integer numeric value. In other words,
it takes a string that contains numbers and returns the corresponding
numeric value.
The VAL command is very useful when working with user input, because
the user often enters numbers as strings. For example, if we ask the
user to enter their age, the input will be a string. In order to perform
calculations with this age, we must first convert it to a number.

The VAL function reads the string from left to right and stops at the
first character that is not a number. The VAL function ignores spaces at
the beginning of the string. If the string does not begin with a number
or contains only non-numeric characters, the VAL function returns zero.

See also STR

Abbreviated as Va
EXAMPLES
1 PRINT VAL ("123")

885
 15 Keywords

15.587 VAR

SYNTAX
VAR variable [AS datatype] [, variable [AS datatype] [ , variable
[AS datatype] ] ]
VAR variable [AS datatype] = constant

PURPOSE

Alias for DIM.

Alias for DIM (variable), DIM
Abbreviated as Vr
EXAMPLES
1 VAR x = 42

886
 15.588 VARBANK

15.588 VARBANK

SYNTAX
= VARBANK( variable )

PURPOSE
Returns the bank assigned for the given variable, -1 if the variable is on
resident memory.

Abbreviated as Vbk
EXAMPLES
1 DIM x as INTEGER : DIM largeArray ( 100 , 100 ) AS INTEGER BANKED
2 x = 42
3 BANK WRITE VARBANK ( largeArray ) FROM VARPTR ( x ) TO
VARBANKPTR ( largeArray ) SIZE 2

887
 15 Keywords

15.589 VARBANKPTR

SYNTAX
= VARBANKPTR( variable )

PURPOSE
Returns the address assigned for the given variable inside a bank of
memory expansion.

Abbreviated as Vbp
EXAMPLES
1 DIM x as INTEGER : DIM largeArray ( 100 , 100 ) AS INTEGER BANKED
2 x = 42
3 BANK WRITE VARBANK ( largeArray ) FROM VARPTR ( x ) TO
VARBANKPTR ( largeArray ) SIZE 2

888
 15.590 VARPTR

15.590 VARPTR

SYNTAX
= VARPTR(var)

PURPOSE
The VARPTR command (short for ”variable pointer”) is a pretty ad-
vanced statement that lets you get the memory address of a variable.
Essentially, it tells you ”where” in memory the value of a specific vari-
able is stored.
In some advanced cases, you may want to directly manipulate the con-
tents of memory. This is useful for things like creating custom data
structures or optimizing the speed of execution of certain operations.

Directly manipulating memory can lead to program errors that are diffi-
cult to detect and correct. If you are not completely sure what you are
doing, it is best to avoid using VARPTR.
Abbreviated as Vp
EXAMPLES
1 address = VARPTR ( x )

889
 15 Keywords

15.591 VIOLET (constant)

SYNTAX
= VIOLET

PURPOSE
This keyword represents the color violet. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (204,68,204). However,
not all computers have this color. In which case, it is approximated by
the closest color available, which is usually also used in decoding images
to identify the color to use.
Abbreviated as Vi

EXAMPLES
1 PEN VIOLET

890
 15.592 VOLUME

15.592 VOLUME

SYNTAX
VOLUME #[value] ON #[channels]
VOLUME [volume] ON [channels]

PURPOSE
This command allows you to change the volume at which the audio is
generated. In general, you can change the overall audio, or that of each
individual voice.
Abbreviated as Vo
AVAILABLE ON

atari c128 c128z c64 coleco cpc msx1 plus4

EXAMPLES
1 VOLUME #255
2 VOLUME #0 ON #%001
3 VOLUME massimo
4 VOLUME zero ON voice1

891
15 Keywords

15.593 VOLUME MAX

SYNTAX
= VOLUME MAX

PURPOSE
Maximum value usable for audio volume.
Abbreviated as VoMx

892
 15.594 VOLUME MIN

15.594 VOLUME MIN

SYNTAX
= VOLUME MIN

PURPOSE
Minimum value usable for audio volume.
Abbreviated as VoMn

893
 15 Keywords

15.595 VOLUME OFF

SYNTAX
VOLUME OFF ON #[channels]
VOLUME OFF ON [channels]

PURPOSE
This command allows you to mute the audio. In general, you can mute
the overall audio, or each individual voice.

Abbreviated as VoOf
AVAILABLE ON
atari c128 c128z c64 coleco cpc msx1 plus4

EXAMPLES
1 VOLUME OFF
2 VOLUME OFF ON #%001
3 VOLUME OFF ON voice1

894
 15.596 WAIT

15.596 WAIT

SYNTAX
WAIT cycles [CYCLES] [PARALLEL]
WAIT ticks TICK
WAIT ticks TICKS
WAIT time MILLISECOND
WAIT time MILLISECONDS
WAIT time MS

PURPOSE
Pauses execution for a certain period of time. The WAIT statement
can be accompanied by a suffix statement, which indicates the unit of
measurement of the time to wait. The suffix CYCLES can be used to
indicate CPU cycles, TICKS to indicate the number of vertical blanks
at 50Hz (PAL) or 60Hz (NTSC), and MS (MILLISECONDS) to indicate
a number of milliseconds.
The pause is of the ”busy” type, so the entire program is suspended,
except for the timer-related mechanisms but including the multithread-
ing mechanism. To avoid this, you can follow the instruction with the
PARALLEL keyword, which allows parallel processes to continue execut-
ing while waiting for the time.
The PARALLEL keyword can only be used with waits related to CYCLES.
Abbreviated as Wt

EXAMPLES
1 WAIT #42 CYCLES

895
 15 Keywords

15.597 WAIT FIRE

SYNTAX
WAIT FIRE [(port)] [RELEASE]

PURPOSE
This instruction allows you to wait for the pressure of the FIRE key
on the joystick. If the port number is not indicated, it means the first
available (the one with index 0). If the keyword RELEASE is appended,
the instruction will wait for the release of the key, as well.
Abbreviated as WtFi
EXAMPLES
1 WAIT FIRE

896
 15.598 WAIT KEY

15.598 WAIT KEY

SYNTAX
WAIT KEY [RELEASE]

PURPOSE
This instruction allows you to wait for any key to be pressed key on
the keyboard. If the keyword RELEASE is appended, the instruction will
wait for the release of the key, as well.

Abbreviated as WtKy
EXAMPLES
1 WAIT KEY

897
 15 Keywords

15.599 WAIT KEY OR FIRE

SYNTAX
WAIT KEY OR FIRE [([port])] [RELEASE]

PURPOSE
This instruction allows you to wait for the pressure of the FIRE key
on the joystick or any key from keyboard. If the port number is not
indicated, it means the first available (the one with index 0). If the
keyword RELEASE is appended, the instruction will wait for the release
of the key / fire button, as well.
Abbreviated as WtKyORFi
EXAMPLES
1 WAIT KEY OR FIRE

898
 15.600 WAIT PARALLEL

15.600 WAIT PARALLEL

SYNTAX
WAIT PARALLEL id

PURPOSE
The WAIT PARALLEL command allows you to wait for the completion
of a previously running mandatory thread. In order for the thread to be
considered completed, it must reach the last statement of the parallel
procedure, or have executed the EXIT PROCEDURE command.
Abbreviated as WtPr
EXAMPLES
1 WAIT PARALLEL exampleThread

899
 15 Keywords

15.601 WAIT UNTIL

SYNTAX
WAIT UNTIL expression

PURPOSE
The WAIT UNTIL command allows you to suspend the execution of a
thread until the indicated condition becomes TRUE. In other words, the
expression is evaluated and, if FALSE, the execution will be suspended
to send another scheduled thread to execute. If it becomes TRUE, the
execution of this thread will continue.
Abbreviated as WtUn
EXAMPLES
1 WAIT UNTIL x < 0

900
 15.602 WAIT VBL

15.602 WAIT VBL

SYNTAX
WAIT VBL [raster line]

PURPOSE
The WAIT VBL command pauses program execution until a ”vertical
blank” is encountered. This is a signal that is triggered at each screen
refresh, which usually occurs at 50 Hz in PAL standard and 60 Hz in
NTSC standard.
Some video chipsets also allow you to specify a specific raster line, so
execution will continue when that specific line is reached. If the chipset
does not allow this, this constraint will be ignored, while still respecting
the arrival of a vertical blank.

Abbreviated as WtVb
AVAILABLE ON
atari atarixl c128 c128z c64 c64reu coco coco3 cpc pc128op
plus4 to8 vic20

EXAMPLES
1 WAIT VBL 100

901
 15 Keywords

15.603 WAIT WHILE

SYNTAX
WAIT WHILE expression

PURPOSE
The WAIT WHILE command allows you to suspend the execution of a
thread until the indicated condition becomes FALSE. In other words, the
expression is evaluated and, if TRUE, the execution will be suspended
to send another scheduled thread to execute. If it becomes FALSE, the
execution of this thread will continue.
Abbreviated as WtWh
EXAMPLES
1 WAIT WHILE NOT done

902
 15.604 WHILE...WEND

15.604 WHILE...WEND

SYNTAX
WHILE expression
...
WEND

PURPOSE

This instruction define a conditional loop, or a list of statements that

will be executed while an expression is true. WHILE acts as the starting
position while WEND as the ending one. This command provides a con-
venient way of making the program repeat a group of instructions all
the time a particular condition is true. The condition is checked again
at every turn of the loop, until it is no longer true.

See also DO...LOOP, REPEAT...UNTIL, FOR...NEXT

Abbreviated as WhWe
EXAMPLES
1 WHILE alive
2 score = score + 1
3 WEND

903
 15 Keywords

15.605 WHITE (constant)

SYNTAX
= WHITE

PURPOSE
This keyword represents the color white. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (255,255,255). However,
not all computers have this color. In which case, it is approximated by
the closest color available, which is usually also used in decoding images
to identify the color to use.
Abbreviated as Wht

EXAMPLES
1 PEN WHITE

904
 15.606 WIDTH (constant)

15.606 WIDTH (constant)

SYNTAX
= WIDTH

PURPOSE
Alias for SCREEN WIDTH.
Alias for SCREEN WIDTH (constant)

Abbreviated as Wd
EXAMPLES
1 IF WIDTH > 128 THEN : PRINT " At least 128 pixels !!": ENDIF

905
 15 Keywords

15.607 WORD (data type)

SYNTAX
... AS WORD

PURPOSE
The WORD is a data type that allow to store a 16-bit word.
Abbreviated as Wo

EXAMPLES
1 DIM parolaLunga AS WORD

906
 15.608 X CURS

15.608 X CURS

SYNTAX
= X CURS

PURPOSE
Alias for XCURS
Abbreviated as XCURS

907
 15 Keywords

15.609 X GRAPHIC

SYNTAX
= X GRAPHIC(x)

PURPOSE
This function performs the conversion of text abscissa to graphic ab-
scissa, and can be used to position text over an area of graphics on the
screen.

Alias for XGRAPHIC

Abbreviated as XGr
EXAMPLES
1 x = X GRAPHIC (10)

908
 15.610 X TEXT

15.610 X TEXT

SYNTAX
= X TEXT(x)

PURPOSE
This function performs the conversion of graphic abscissa to text ab-
scissa, and can be used to position an area of graphics on the screen,
over the text.

Alias for XTEXT

Abbreviated as XTx
EXAMPLES
1 x = X TEXT (100)

909
15 Keywords

15.611 XCURS

SYNTAX
= XCURS

PURPOSE
Returns the X value of the cursor position.
Alias for X CURS

Abbreviated as Xcs

910
 15.612 XGR

15.612 XGR

SYNTAX
= XGR

PURPOSE
Returns the X value of the last graphical position.

911
15 Keywords

15.613 XGRAPHIC

SYNTAX
PURPOSE

Alias for X GRAPHIC.

Alias for X GRAPHIC
Abbreviated as Xg

912
 15.614 XOR

15.614 XOR

SYNTAX
= x OR y

PURPOSE
Performs a logical exclusion on two expressions, as a bitwise exclusion.
For comparisons managed as a boolean result (TRUE or FALSE), result
is TRUE if both expresions evaluate differently each other. The following
table shows how result is determined:
TRUE XOR TRUE = FALSE
TRUE XOR FALSE = TRUE
FALSE XOR TRUE = TRUE
FALSE XOR FALSE = FALSE

Generally speaking, the XOR operator performs a bitwise comparison of

the bits of two numeric expressions and sets the corresponding bit in
result according to the previous table.
Note that ugBASIC uses the convention, very common in BASICs of the
1970s and 1980s, of considering Boolean logic as implemented through
the so-called ”two’s complement”.
In other words, the value FALSE is associated with a number composed
of all 0s, in terms of bits. The value TRUE is, instead, associated with a
number composed of all 1s, again in terms of bits. According to the 2’s
complement representation, a number composed of all ones is always
equivalent to the number -1, regardless of how many bits the number is
composed of, while a number composed of all zeros is always equivalent
to zero.
According to this convention, there is a coincidence between bitwise

913
 15 Keywords

and logical operations: in fact, a bitwise XOR, applied to all the bits
of the number, will be equivalent to the logical operation. Note that
the XOR operator always evaluates both expressions, which can include
executing routine calls.

Because the logical and bitwise operators have lower precedence than
other arithmetic and relational operators, all bitwise operations must be
enclosed in parentheses to ensure accurate results.
If the operands consist of a SIGNED BYTE expression and a numeric
expression, converts the SIGNED BYTE expression to a numeric value
(-1 for TRUE and 0 for FALSE) and performs a bitwise operation. So,
the data type of the result is a numeric type appropriate for the data
types of both expressions.
Abbreviated as Xr

EXAMPLES
1 IF x XOR x THEN : PRINT " never executed " : ELSE : PRINT " always
executed ": ENDIF

914
 15.615 XPEN

15.615 XPEN

SYNTAX
= XPEN( )

PURPOSE
Read the X (horizontal) position of the electronic pen connected to the
hardware.

Abbreviated as Xp
AVAILABLE ON
atari c128 c64 plus4 vic20
EXAMPLES
1 x = XPEN ( )

915
15 Keywords

15.616 XTEXT

SYNTAX
PURPOSE

Alias for X TEXT.

Alias for X TEXT
Abbreviated as Xt

916
 15.617 Y CURS

15.617 Y CURS

SYNTAX
= Y CURS

PURPOSE
Alias for YCURS
Abbreviated as YCURS

917
 15 Keywords

15.618 Y GRAPHIC

SYNTAX
= Y GRAPHIC(y)

PURPOSE
This function performs the conversion of text ordinate to graphic ordi-
nate, and can be used to position text over an area of graphics on the
screen.

Alias for YGRAPHIC

Abbreviated as YGr
EXAMPLES
1 x = Y GRAPHIC (10)

918
 15.619 Y TEXT

15.619 Y TEXT

SYNTAX
= Y TEXT(y)

PURPOSE
This function performs the conversion of graphic ordinate to text ordi-
nate, and it can be used to position an area of graphics on the screen,
over the text.

Alias for YTEXT

Abbreviated as YTx
EXAMPLES
1 x = Y TEXT (100)

919
15 Keywords

15.620 YCURS

SYNTAX
= YCURS

PURPOSE
Returns the Y value of the cursor position.
Alias for Y CURS

Abbreviated as Ycs

920
 15.621 YELLOW (constant)

15.621 YELLOW (constant)

SYNTAX
= YELLOW

PURPOSE
This keyword represents the color yellow. Depending on the methodol-
ogy and technique, as well as the available hardware, it can correspond
to a specific color in the RGB space, usually (238,238,119). However,
not all computers have this color. In which case, it is approximated by
the closest color available, which is usually also used in decoding images
to identify the color to use.
Abbreviated as Ye

EXAMPLES
1 PEN YELLOW

921
 15 Keywords

15.622 YELLOW GREEN (constant)

SYNTAX
= YELLOW GREEN

PURPOSE
This keyword represents the color yellow green. Depending on the
methodology and technique, as well as the available hardware, it can
correspond to a specific color in the RGB space. However, not all com-
puters have this color. In which case, it is approximated by the closest
color available, which is usually also used in decoding images to identify
the color to use.
Abbreviated as YeGre

EXAMPLES
1 PEN YELLOW GREEN

922
 15.623 YGR

15.623 YGR

SYNTAX
= YGR

PURPOSE
Returns the Y value of the last graphical position.

923
15 Keywords

15.624 YGRAPHIC

SYNTAX
PURPOSE

Alias for Y GRAPHIC.

Alias for Y GRAPHIC
Abbreviated as Yg

924
 15.625 YIELD

15.625 YIELD

SYNTAX
YIELD

PURPOSE
This keyword will suspend the current thread, waiting for the next slice
of time.

Abbreviated as Yi
EXAMPLES
1 YIELD

925
 15 Keywords

15.626 YPEN

SYNTAX
= YPEN( )

PURPOSE
Read the Y (vertical) position of the electronic pen connected to the
hardware.

Abbreviated as Yp
AVAILABLE ON
atari c128 c64 plus4 vic20
EXAMPLES
1 y = YPEN ( )

926
 15.627 YTEXT

15.627 YTEXT

SYNTAX
PURPOSE

Alias for Y TEXT.

Alias for Y TEXT
Abbreviated as Yt

927
 16 Advanced topics

16.1 Resources and targets

The ugBASIC compiler has an automatic and transparent mechanism

to differentiate those resources whose content is tied to the target.
This could be loading images, music, or other specific elements, such
as pre-assembled routines.
In general, for any load statement, such as LOAD IMAGE or LOAD MUSIC,
the name of the files to be loaded is inferred. Before attempting to load
the actual file, a subfolder with the same name as the target is searched
for. If such a subfolder exists, and the same file is found in it, then that
will be loaded instead of the original. Otherwise, the original will be
loaded.
For example, suppose we have this statement:
1 arrow1 := LOAD IMAGE (" images / arrow1 . png ")

and suppose we have a file organization under images/ as follows:

929
16 Advanced topics

ugBASIC will load the image arrow1.png from the images/atari

directory (if the file is present) if the source is compiled for Atari 400/800
target, from images/zx (if the file is present) if the source is compiled
for ZX Spectrum, and so on, while for all targets that do not have a
specific folder or if the file is missing from that folder, it will load the
same image from the images/ directory.

16.2 Game loop

The game loop is a fundamental concept in video game programming,

especially in simple video games like those for 8-bit computers. Think
of the game loop as the heartbeat of a video game: it is a continuous
cycle of actions that are constantly repeated, giving life to the gaming
experience.
In simple terms, the game loop is an infinite loop in the game code that
takes care of:

• updating the game state - checking user input (button presses,

joystick movement), updating the position of objects on the screen,
calculating collisions, managing enemy AI, etc.
• rendering the screen - drawing everything that needs to be dis-
played on the screen, based on the current state of the game.

On an 8-bit computer, with limited resources, the game loop was often
implemented in a very simple way:

• infinite loop - a command such as BEGIN GAMELOOP or a similar

construct was used to create an infinite loop, so that the program
would continue to execute the same instructions over and over
again.
• updates - inside the loop, instructions were executed to update

930
 16.3 Using TILED

the game state, such as checking if a button had been pressed or

if an enemy had moved.
• screen refresh - after updating the state, a routine was called to
draw everything on the screen.

• return to the beginning of the loop - using a command such

as END GAMELOOP, the program would return to the beginning of
the loop, ready for the next iteration.

The game loop makes the game interactive, allowing the player to hit
what is happening on the screen. Continuously updating the state and
redrawing the screen creates the illusion of movement and animation.
A well-designed game loop ensures a smooth and responsive gameplay
experience.

16.3 Using TILED

Tiled is a 2D level editor that helps to develop the content of any tile-
based game. Its primary feature is to edit tile maps of various forms, and
to support free image placement as well as powerful ways to annotate
your level with extra information, that can be used by ugBASIC.
Download Tiled from here:
https://www.mapeditor.org/

16.3.1 Introduction

For the uninitiated, a tile-based video game is based on the fact that
the playing area is made up of small square graphic images (rectangular,
parallelogram, hexagonal) called precisely tiles.
Basically it acts like a piece of a puzzle for building large images. These

931
16 Advanced topics

are then arranged in a grid, or a tilemap, which creates a visually ap-

pealing slice.
The ugBASIC language gives to programmers access to a real ”tile
engine”, that construit the final graphics by arranging tiles in specific
positions, until the intended area is covered.
The complete set of tiles available for use in a play area is together
called tileset.
There are several benefits to using a tile engine.

• limited number of images required - this will shorten develop-

ment time and reduce the size of games;
• image compression - having fifty 320x200pixels images for a
game of fifty levels, or having a single image with 100 tiles makes
a huge difference, in terms of space occupied;
• isomorphism with hardware - the fact that the screen is made
up of such tiles is a wonderfully technical distinction, since many
home computers from the late 1970s to the mid-1990s had more
or less native support for displaying screens of tiles (ugBASIC try,
as usual, to give an isomorphic approach to the topic).

16.3.2 Basic concept: TILESETs

The first primitive that ugBASIC provides is the TILESET. The TILESET
is, conceptually, equivalent to the already known IMAGES (or ATLAS)
data type. With a small but substantial difference: every single image
can be ”described” and becomes functional for the program written in
ugBASIC. For this reason, a TILESET must necessarily be created with
an external tool, such as Tiled, and stored in one of the typical formats
such as the ”tsx” format.
So let’s take an example file like Kenney’s ”Tiny Town”. This file is

932
 16.3 Using TILED

made of 132 tiles, which reproduce the typical architectural and land-
scape elements of a small medieval city.
If we open it, we will see these elements. Now let’s write the ugBASIC
instruction that will allow loading the tileset in its entirely:
1 tileset := LOAD TILESET (" kenney - tiny - town . tsx ")

That’s all. From now on we can use the classic syntax of PUT IMAGE
(or BLIT IMAGE) with the FRAME instruction, to draw any of the 132
tiles on the screen.
1 PUT IMAGE tileset FRAME 29 AT 0 ,0

Note that instead of the keyword FRAME, it is possible to use the keyword
TILE. Furthermore, it is possible to limit the drawing to the bitmap
component only (therefore without the color component) or possibly
carry out BLITting operations. In other words, these instructions are
fully equivalent:
1 BLIT put AS SOURCE
2 PUT IMAGE tileset TILE 29 AT 0 ,0
3 BLIT IMAGE tileset FRAME 29 AT 0 ,0 WITH put
4 BLIT IMAGE tileset TILE 29 AT 0 ,0 WITH put

16.3.3 Just a single TILE

Tiled allows you to load an image already made up of tiles and gives
access to a convenient panel, which allows you to modify, individually,
the properties of each single tile.
In particular, each tile has the following properties:

• id - identification of the tile (read only);

• class - class of the tile;
• width - width of the tile, in pixels (read-only);

933
 16 Advanced topics

• height - height of the tile, in pixels (read-only);

• probability - probability of selecting this tile.

Each of these fields maps to certain keywords or parameters of ugBASIC:

1 PUT IMAGE tileset TILE [ id ] AT [ x ] ,[ y ]
2 class = TILE CLASS ( tileset , tile )
3 width = TILE WIDTH ( tileset )
4 height = TILE HEIGHT ( tileset )
5 probability = TILE PROBABILITY ( tileset , tile )

Also, you can draw a tile using its class:

1 PUT IMAGE tileset TILE # mushroom AT 32 ,32

16.3.4 Basic concept: TILEMAPs

With TILESET element we can draw one TILE at a time on the screen,
where we want. However, it would be nice to be able to draw and rep-
resent whole maps, exactly as Tiled allows. The ugBASIC compiler will
make available the TILEMAP datatype that will serve just the purpose:
to represent a map of those drawn by means of Tiled.

To use it, simply load the ”tmx” file:

1 tilemap := LOAD TILEMAP (" kenney - tiny - town . tmx ")

To draw it on the screen you can use the PUT TILEMAP statement:
1 PUT TILEMAP tilemap

Note how the same map draws the same way on different screens. The
map is however within the available screen size. But what if the map
was bigger? Simple: it only draws a part of the map, just like we
expected. Note that each computer has its own resolution, so it would
be appropriate to decline the maps and tiles according to the target.

934
 16.4 Retro (compatible) hacks

This is always possible thanks to the mechanism of the folder linked to

the target. To scroll the map we have to use the FROM parameter, as
follows:
1 PUT TILEMAP tilemap FROM [ dx ] ,[ dy ]

The [dx] and [dy] values are the offsets (in terms of tiles) starting from
which the map will have to be drawn on the screen. So, for example,
with this command:
1 PUT TILEMAP tilemap FROM 2 , 1

we are drawing tiles starting one position down and two positions to the
right. Obviously we are not forced to consider these values as constants:
introducing them in a loop, we can scroll the map along one direction,
or both. Using the TILEMAP WIDTH and TILEMAP HEIGHT commands
we can obtain, in fact, the extremes within which to scroll. Clearly,
scrolling is downright slow. However, it is possible to improve it and
make it more fluid, but it requires the introduction of other primitives.

16.4 Retro (compatible) hacks

Sometimes developing new features makes the compiler different from

how it was before they were developed. When this happens, the author
try to introduce specific options (OPTION or DEFINE) to be able to ”go
back” (or, more often, to activate the new behaviors). Also, before
publishing a release of the compiler, a recompilation of all the games
released so far and for which the author have the sources is performed.

However, no matter how much care you put into the process: sometimes
the changes make the compiler backwards incompatible. This is what
happened, for example, with the introduction of the FOR that can go
forward and backward, with the analog reading of the joystick and,
above all, by fixing a problem with the optimizer.

935
16 Advanced topics

To avoid giving disservice to those who want to recompile sources writ-

ten in the past with the new compilers, ugBASIC will always contain
what the author called ”retro (compatible) hacks”: these are changes
to the compiler’s behavior that are based on the fact that a certain
source is being compiled. At the moment there are four:

• rchack ccarrots 1163 - for Creepy Carrots;

• rchack falling balls 1163 - for FALLING BALLS (10 liner);
• rchack 4gravity 1163 - for 4GRAVITY!;
• rchack pick the star 1163 - for PICK THE STAR (10 liner);

• rchack cocon 1163 - for The Savage Sword of COCON;

You do not need to do anything to activate these hacks because they

are based on the filename of the source.

16.5 Endianess

Endianness is a concept that concerns the order in which the bytes of a

multi-byte number are stored in memory. Imagine having an integer that
spans more than one byte. Endianness determines whether the most
significant byte (the one that represents the highest digit) is stored first
(at the lowest memory address) or last.

There are two main types of endianness:

• big-endian - in this case, the most significant byte is stored first.

It is like reading a book from left to right, starting with the most
important word.
• little-endian - in this case, the least significant byte is stored
first. It is like reading a book from right to left, starting with the

936
 16.6 Directives (or ”pragma”)

least important word.

Endianness is a fundamental aspect of computer architecture, as it af-

fects how data is interpreted and manipulated. Different architectures
use different endianness conventions.
For example:

• MOS 6502/6510/8502: little-endian

• Zilog Z80: little-endian

• Motorola 6809: big-endian

In 8-bit computers, endianness was a crucial consideration, especially

when it came to managing integers across multiple bytes. Since these
computers had limited memory, it was essential to maximize storage
space. With limited memory available, it was essential to use each byte
efficiently. Endianness directly affected arithmetic operations on multi-
byte numbers, such as addition and subtraction. When exchanging data
between systems with different endianness, appropriate conversions were
needed.

If you are writing code that directly manipulates memory, it is essential

to know the endianness of the system to avoid data interpretation errors.
When exchanging data over a network, it is important to ensure that
both systems use the same endianness convention. If you are developing
software that needs to run on different platforms, you need to account
for endianness differences and implement data conversion mechanisms,
for data not manager by ugBASIC itself.

16.6 Directives (or ”pragma”)

The ugBASIC language allows you to modify the behavior and param-
eters of the compilers, as well as the functionality it exposes. To this

937
16 Advanced topics

purpose it introduces what are called ”pragmas” (or directives). In a

nutshell, there are three kind of directives:

• the language directives, which modify the behavior of the actual

language, and are prefixed by the OPTION keyword;

• the feature directives, which modify the behavior of some avail-

able features, such as the management of dynamic strings, and
are prefixed by the DEFINE keyword;
• the hardware directives, which modify the integration with ded-
icated hardware, such as the address where the sound cards are
located, which are prefixed by the CONFIGURE keyword.

The syntax of each of these directives is different, and so we address

them in separate sections.

16.6.1 Language directives

Language directives allow you to modify the behavior of the language

or compiler, to ensure that it behaves as expected. They are all prefixed
by the OPTION keyword, and they work from the next instrucion. Below
is thelist of options supported by the language.

OPTION TYPE WIDE/NARROW

This directive changes the way ugBASIC interpret constants, possibly

using the default type.
The first approach (OPTION TYPE WIDE) is the standard one: in this
mode, the constant number is converted into the default data type,
which is the INT (SIGNED WORD) type (unless redefined), and it will
occupy 2 bytes.

938
 16.6 Directives (or ”pragma”)

The second approach (OPTION TYPE NARROW) is the optimized one: in

this mode, the number is converted into the smallest data type capable
of containing the number. So, i.e., 42 is converted to a SIGNED BYTE
value that occupies 1 byte.

OPTION TYPE SIGNED/UNSIGNED

This directive changes the way ugBASIC interpret constants, allowing

the use of signed type.
The first approach (OPTION TYPE SIGNED) is the standard one: in this
mode, the constant number is converted into the (signed) default data
type, which is the INT (SIGNED WORD) type (unless redefined).
The second approach (OPTION TYPE UNSIGNED) makes the constant
number converted into the (unsigned) default data type, which is the
WORD type (unless redefined).

OPTION EXPLICIT OFF/ON

By using this pragma, ugBASIC will require that each variable or con-
stant used has been previously defined, to be used. It will therefore no
longer be possible to use variables defined ”on the fly” but they will
have to be, at least, defined using DIM.

This pragma can be used ad any point of the program: when you add
this pragma alone (without ON) it means that you activate the explicit
definition. So, ugBASIC will emit a compile error and it highlight the
variable in the code that need to be declared.
It can be also disabled using the OFF parameter:

939
16 Advanced topics

OPTION READ SAFE/FAST

By using OPTION READ SAFE, ugBASIC will will try to identify the
type of data stored with the DATA instruction, and to convert it into the
variable type used by the READ command. This is the default behaviour,
that is the one more similar to the original BASIC command.

On the other hand, by using OPTION READ FAST, ugBASIC will assume
that DATA instruction’s value are stored in the same data type of the
variable used to read them.

OPTION CLIP ON/OFF

By using the OPTION CLIP ON, you enable the clipping on PLOT in-
struction (and similar). This is the default behaviour.

By using the OPTION CLIP OFF, you disable the clipping.

OPTION CALL AS GOSUB/GOTO

By using the OPTION CALL AS GOSUB, you makes CALL synonym for
GOSUB, so that the execution will return back to the calling point (de-
fault behaviour).

On the other hand, by using the OPTION CALL AS GOTO, you makes
CALL synonym for GOTO, so that the execution will not return back to
the calling point.

OPTION EXEC AS GOSUB/GOTO

If OPTION EXEC AS GOSUB is used, and EXEC is used to call a proce-

dure, instruction will be a synonym for GOSUB, so that the execution

940
 16.6 Directives (or ”pragma”)

will not return back to the calling point (default behaviour).

On the other hand, if OPTION EXEC AS GOTO is used, and EXEC is used
to call a procedure, instruction will be a synonym for GOTO, so that
the execution will not return back to the calling point.

OPTION DIALECT dialect

In principle, ugBASIC has a well-defined and specific syntax and se-

mantics, and it also incorporates the syntax of other dialects. However,
sometimes dialects conflict on specific aspects. In such cases, it is
not possible to automatically determine which behavior to follow. This
pragma allows you to indicate what the interpretation of commands
should be.
Valid values for dialect are:

• UGBASIC : enable ugBASIC behaviour (default)

• TSB : enable Tuned Simons’ BASIC behaviour

OPTION DEFAULT TYPE type

Change the default type of variables, if not specified.

16.6.2 Feature directives

Features directives allow you to modify the behavior of the some avail-
able features, to ensure that it behaves as expected. They are all pre-
fixed by the DEFINE keyword, and they work globally (unless specified).
Below is the concise list of defines supported by the language.

941
16 Advanced topics

DEFINE AUDIO SYNC/ASYNC

By using the DEFINE AUDIO SYNC, audio effects and music notes are
played synchronously, so no need to wait for completition for executing
the next command.

By using the DEFINE AUDIO ASYNC, audio effects and notes are played
asynchronously, so you need to wait for completition otherwise the fol-
lowing commands will be executed during the sound effect/note.

DEFINE AUDIO TARGET device

With this pragma you can specify the output for audio commands. This
pragma is target specific, so the valid values for device change based
on target:

• atari, atarixl : POKEY

• c128, c64, c64reu : SID

• coco, coco3 : DAC1, SN76489
• coleco, pc128op, sc3000, sg1000 : SN76489

• cpc, msx1 : AY8910

• plus4 : TED
• vic20 : VIC

Please note that some of these parameters require additional hardware.

942
 16.6 Directives (or ”pragma”)

DEFINE CENTER WITH/WITHOUT NEWLINE

The CENTER WITH NEWLINE pragma enables implict newline instruction

with CENTER command, if ; is not appended (default behaviour).
On the other hand, CENTER WITHOUT NEWLINE pragma disable implict
newline instruction with CENTER command, if ; is not appended. So
you need an additional PRINT to move to the next line.

DEFINE CLS EXPLICIT/IMPLICIT

The CLS EXPLICIT pragma disables the execution of CLS command

when resolution is changed, and at startup (default behaviour).
On the other hand, CLS IMPLICIT pragma enables the execution of
CLS command when resolution is changed, and at startup.

DEFINE COLOR EXPLICIT/IMPLICIT

By using the DEFINE COLOR EXPLICIT, the color index used into graph-
ical commands is exactly the color to use (default behaviour).
On the other hand, it DEFINE COLOR IMPLICIT is used, the color index
used into graphical commands is one of the current supported palette.

DEFINE DOUBLE BUFFER OFF/ON

The DEFINE DOUBLE BUFFER OFF means that graphics and images
routines will leave the code to manage both double buffering and not
(default behaviour).
The DEFINE DOUBLE BUFFER ON means that graphics and images rou-
tines will take out the code to manage non double buffer mode (or

943
16 Advanced topics

double buffer mode), based on the fact that double buffer mode is
enabled.

DEFINE COMPRESSION RLE OFF/ON

This pragma allows you to enable or disable RLE compression, where

available.

DEFINE FLOAT PRECISION precision

Changes the precision level of floating point number representation.

Possible valus for precision are:

• FAST : fast floating points (at least 24 bit)

• SINGLE : fast floating points (at least 32 bit)

Note that not all targets handle this pragma: in some, the floating point
precision is fixed.

DEFINE FONT schema

Change the preloaded font for graphical modes, and modes where char-
acters can be redefined.

Possible valus for schema are:

• EMBEDDED : no font will be preloaded, the embedded one will be

used
• STANDARD : standard font (128 characters, ASCII only) will be
preloaded

944
 16.6 Directives (or ”pragma”)

• SEMIGRAPHIC : standard font with semigraphic characters (256

characters) will be preloaded
• COMPLETE : standard font with complete character set (256 char-
acters) will be preloaded

DEFINE LOAD BANKED OFF/ON

If DEFINE LOAD BANKED OFF is used, images will be loaded on resi-

dent memory when no BANKED instruction is used along with the LOAD
command.
If DEFINE LOAD BANKED ON is used, images will be loaded on expansion
memory when no UNBANKED instruction is used along with the LOAD
command.
Please note that this pragma only works with commands related to
graphic resources (images, atlas and sequences), and that the default
pragma is different depending on the target.

DEFINE INPUT SIZE size

This pragma will change the maximum size for keyboard buffer used by
INPUT$() instruction.

DEFINE INPUT SEPARATOR char

This pragma will change the character that will be used to separate
input elements, when multiple variables are used on INPUT command.

945
16 Advanced topics

DEFINE INPUT CURSOR char

This pragma will change the character that will be used as cursor during
input.

DEFINE INPUT/KEYBOARD RATE value

This pragma will change the rate of keyboard repeating during input,
expressed as one character for each value video ticks.

DEFINE INPUT/KEYBOARD RATE milliseconds MS

This pragma will change the rate of keyboard repeating during input,
expressed as one character for each milliseconds.

DEFINE INPUT/KEYBOARD DELAY value

This pragma will change the delay of keyboard start repeating during
input, expressed as one character for each value video ticks.

DEFINE INPUT/KEYBOARD DELAY milliseconds MS

This pragma will change the delay of keyboard start repeating during
input, expressed as one character for each milliseconds.

DEFINE JOYSTICK RETRIES number

This pragma will change the number of readings when retrieving value
from analogical joystick.

946
 16.6 Directives (or ”pragma”)

DEFINE JOYSTICK SYNC/ASYNC

If DEFINE JOYSTICK SYNC pragma is used, the program will read the
position of joysticks in the moment the program asks for them.
On the other hand, DEFINE JOYSTICK ASYNC pragma is used, the pro-
gram will read the position of joysticks during interrupt, giving back the
last value read when the program asks for it.

Please note that the default pragma is different depending on the target.

DEFINE KEY PRESS SYNC/ASYNC

If DEFINE KEY PRESS ASYNC is used, the KEY PRESS command will
follow the standard behaviour. Otherwise, if DEFINE KEY PRESS ASYNC
is used, KEY PRESS will be an alias for KEY STATE.

DEFINE KEYBOARD SYNC/ASYNC

If DEFINE KEYBOARD SYNC pragma is used, the program will read the
key pressed in the moment the program asks for them.
On the other hand, DEFINE KEYBOARD ASYNC pragma is used, the pro-
gram will read the key pressed during interrupt, giving back the last
value read when the program asks for it.
Please note that the default pragma is different depending on the target.

DEFINE MSPRITE SYNC/ASYNC

If DEFINE MSPRITE SYNC pragma is used, changes made to multiplexed

sprites will be immediate, meaning they will be reflected in the next

947
16 Advanced topics

update. This will cause the program to wait for the update before
proceeding.
On the other hand, DEFINE MSPRITE ASYNC pragma is used, changes
made to multiplexed sprites will be stored and reflected on the screen
only when the instruction MSPRITE UPDATE will be executed.

DEFINE PALETTE [NOT] PRESERVE

The DEFINE PALETTE PRESERVE enables palette preservation. This

mechanism means that if a palette register has been allocated with a
color, that register will retain the color even if a change is requested.

The DEFINE PALETTE NOT PRESERVE disables palette preservation.

Note that not all targets handle this pragma.

DEFINE PROGRAM START address

Change the starting address of the executable program to address.

There may be limits on the addresses that can be used, and in any case
the programs start from a different address, depending on the target:

• atari, atarixl : default starting address is &H2000. The ad-

dress can be increased up to the low address of the frame buffer
area.

• c128 : default starting address is &H1c0e. The address can be

increased, but the starting load address will be always &H1bff
since this is the default address for BASIC V2 launcher.
• c128z : default starting address is &H1c2f. The address can be
increased, but the starting load address will be always &H1bff

948
 16.6 Directives (or ”pragma”)

since this is the default address for BASIC V7.0 launcher with the
code to activate Zilog Z80 processor.
• c64, c64reu : default starting address is &H080e. The address
can be increased, but the starting load address will be always
&H0801 since this is the default address for BASIC V2 launcher.
• coco, coco3 : default starting address is &H2a00. The address
can be increased, but the starting load address will be always
&H2a00 since this is the default address that is used by BASIC
launcher.

• cpc : Default starting address is &H0100.

• d32, d64 : default starting address is &H2800. The address can
be increased, but the starting load address will be always &H2800
since this is the default address that is used by BASIC launcher.

• mo5, pc128op : default starting address is &H3000. Note that,

if you change this address, you could need to reserve more space
from embedded BASIC to load the program.
• vic20 : default starting address is &H2000. The address can
be increased, but the starting load address will be always &H1fff
since this is the default address for BASIC V2 launcher.

Note that not all targets handle this pragma.

DEFINE PAINT BUFFER size

Change the size of buffer used as stack for PAINT instruction.

949
16 Advanced topics

DEFINE SCREEN MODE UNIQUE

Limit the support to just one screen mode, discarding routines and data
structures for the other.

DEFINE STRING COUNT number

Change the maximum number of dynamic strings that can be stored at

the same time.

DEFINE STRING SPACE size

Change the maximum size of dynamic strings that can be stored at

the same time.

DEFINE TASK COUNT number

Change the maximum number of tasks that will be managed using

multitasking.

16.6.3 Hardware directives

In order to allow customization of the hardware, and the possibility of

generating hardware selection menus via software. The configuration
allows two types of manipulation: a static one, which is adopted at
compilation time (useful for development and unconventional startup)
and a dynamic one, which is adopted at execution time (useful for
creating configuration menus).

950
 16.6 Directives (or ”pragma”)

Each hardware change request must begin with the CONFIGURE key-
word followed by the name of the hardware to be configured. Static
changes must begin with the CONFIGURE STATIC keywords, while dy-
namic changes must begin with the CONFIGURE DYNAMIC keywords. By
default, the changes are to be considered static.
Each request for hardware modification must concern one or more pa-
rameters prefixed by the SET command. The value that can be assigned
to these variables must be consistent with the expected and acceptable
values, as described next to the parameter. Note that this control will
only take place on static configurations, since they must be constant.
Finally, it is possbile to assign multiple values consecutively, separating
them with a comma, without using the SET command.
For example, this command will configure the audio for coco target, as
the one given from Game Master Cartridge on slot 2 with SN76489:
1 CONFIGURE GMC SET SLOT = 2
2 CONFIGURE SN76489 SET ADDRESS = $FF41

CONFIGURE GMC SLOT number

This is the slot where GMC is installed.

Valid values for number:

• coco, coco3 : default 0, allowed 0-3 (slot 3 is not available if

disk image is used)

• coco, coco3 : default 0, allowed 0-3 (slot 3 is not available if

disk image is used)

CONFIGURE SN76489 ADDRESS address

This is the address where the data and control port appears.

951
16 Advanced topics

Valid values for number:

• pc128op : default &HA7FF, allowed &HA7F6, &HA7F7, &HA7FE,

&HA7FF
• coco, coco3 : default &HFF41

952