Here are some of the pages of the User Guide!

Quick Start

  • RUN "#BURN" (to install ROMs.)
  • |M then ESC, or |O to go directly to the editor.
  • CONTROL-H For online help, available in the editor, monitor, and debugger.
  • CONTROL-I (Import) Loads a DAMS source file, Maxam (ASCII) or TurboAss (exported to ASCII).
  • or: CONTROL-O to open an exemple source (.o files).
  • CONTROL-1 To assemble.
  • SPACE To return to the editor.
  • CONTROL-4 To cycle through the current errors.
  • CONTROL-S to save. CONTROL-O to open.
  • CONTROL-2 To assemble & run.


Like DAMS Orgams breaks down into:

  • Editor (with validation on the fly lines seizures)
  • Monitor (aka "Monogams")
  • Debugger (disassembly, trace step-by-step, etc …)

OrgamS is quite greedy and takes 4 ROMs.

  • ORGAMS.ROM: Base Rom place in any rom position 1 to 15 (or up to 31 with the proper firmware).
  • ORGEXT.ROM: Expansion Rom placed at any rom position 1-127.
  • MONOGAMS.ROM: Monitor placed at any rom position 1-127.
  • BRICBRAC.ROM: Additional additional Rom at any position 1-127.

Several banks are being used (decreasingly), basic bank (bkBase) being:

  • C7 with 128k
  • FF with 512k (allows cohabitation with 256k RAM-DISK).

Then bkBase-1 is used for the mirror system / working memory.
The source begins in bkBase-3.

Screenshots of monitor, editor and trace.

Flow between modules

Here, "Exec" represents the assembled program running.


  • |ORGAMS: opens the monitor and deletes the source code.
  • |ORG, |M: opens the monitor without deleting the source code.
  • |O: opens the editor without deleting the source code.


  • ESC: Goto Ed
  • Order 'basic': (Back) Basic.
  • Command 'DEXP' Goto debugger


  • CTRL-F2: If ok, Goto Exec
  • ESC: Goto Monitor


  • RET: as RESTORE (but the battery must be valid)
  • RESTORE Restores system and Goto Ed.
  • BRK / rst &30 / call &BE00: Goto Trace


  • CONTROL-ESC: Goto Editor to visualized line.
  • ESC: Goto Monitor
  • J: Goto Exec

Programming session example:

  1. Tweaking opcodes via the editor. CONTROL-4 makes it possible to go directly to the reported errors during assembly (CONTROL-1).
  2. Rather than a mere RET, use RESTORE or BRK to quit out of your program.
  3. Save source.
  4. Test by CONTROL-2: it assembles the code and run the program.
  5. The monitor allows to study all memory (except the screen memory this is used by Orgams' display).


Enter the editor using |O from BASIC, or by pressing ESC in the Monitor.
Leave the editor by either pressing ESC, launching assembly + execution (CTRL 2), or by resetting the CPC.

The current session persists across resets, with the source validity check.

Status board

From version EE beta H, the status board displays the following information:

  • Line 1
    • Path in source (in which routine and IF block the cursor currently is).
    • Line number / total lines.
    • Current MMR / RRM selection (like in Monogams)
  • Line 2
    • List of opened sources (a.k.a. tabs)
  • Line 3
    • Dump of current line, with the difference with original code highlighted.
    • Block related information (e.g. machine time taken).
    • Number of Hectibytes free (like in Monogams)
  • Line 4
    • Questions and results of actions.
    • Banks used by Orgams (like in Monogams)
  • Line 5
    • Internal debug information.

It looks like something like that ('.' for border):

.. dev=PRELUDE.GenTexture.loopx.dbg!   133/ 945                                7fc2  LRAM / 0a    ..
..1 orgch     2*crtc     3*cpct     4*         5*         6 nrt    7 player  8 bulgur  9 leprous  ..
..1203: 3E 04 09 90 CA 34 FE 32         100..122: 32 bytes, 64 NOPs                123 Hib free   ..
.. Found: string                                                                  Used: 7fdf-ff   ..
..                                                                                         fc:4534..
.......... ; This is the actual source                                                    ..........
.......... ; idem                                                                         ..........


The first thing you want to do is listen 6:33.
The second will be to import your old tatty sources (see "Write a technical manual for Dummies", how to create "user stories").
Via CONTROL-I, Orgams automatically recognizes source from DAMS and other ASCII sources (TurboASS, Maxam or ORGAMS).
The various adjustments will be made automatically for example:

  • 'NbDots EQU &1000' becomes 'nbDots = &1000'
  • 'Defs 100,nbCols%3' becomes 'FILL 100,nbCols MOD 3'

The operation is very slow because much of the pre-assembly and symbol resolution is done at this time.

Possible differences. !!WARNING!!

Modified Arithmetic.


  • LD A, pal&#ff+1; (pal and #FF) + 1


  • LD A, pal AND &FF+1; pal and &100

Indeed, as &ff+1 is visually grouped, it is therefore calculated separately.
It must be corrected to either of these:

  • LD A, pal AND &FF + 1; Direction left to right
  • LD A, [pal AND &FF]+1

ORG behavior

When DAMS assemble with A2, each ORG changes the PC ($) but not the storage address ($$). However ORGAMS does
not allow this mode. To reproduce the same action it must be explicitly replaced:

  • (DAMS) ORG dest
  • (ORGAMS) ORG dest, $$

1 parameter DEFS

The 'DEFS size' DAMS is replaced by 'F size', resulting in a syntax error.
Indeed, 'F' is known as 'FILL', but only when followed by two mandatory parameters.
With one parameter, DAMS reserves space without initializing it. There is no equivalent in ORGAMS. We must
therefore explicitly write 'F size, 0' (automatically replaced by 'FILL size, 0').


In Monogams, use the X command to compare the assembled code with your referral code.


  • Editing of lines is limited to 72 characters. If asked why, you will say that you do not know.


Keyboard shortcuts are described in the online help (press CONTROL-H).
We concentrate here on more sophisticated.

CTRL + C Displays the catalog of the disk.

CTRL + L str (TAB to continue the search)

Go directly to the next label beginning with "str". This is equivalent to the command 'the DAMS, with the following improvements:

  • Insensitive to breakage
  • You can iterate all labels beginning with "str". Just press CTRL-L again then RETURN to move to the next or just press TAB.

CTRL * (TAB to continue the search)

Go to the next occurrence of the label under cursor (reminiscent VI).
If there is no label under cursor, it takes the first label from this position(*). If there is no such label, it takes the closest to the left.


fx_dispatch call routine; CTRL-* will go to next occurrence of 'fx_dispatch' if the cursor is over
                          ; or next occurrence of 'routine' in all other cases.

(*) Why the label to the right? An article published in "Psychological Science in the Public Interest" shows a tendency to focus on the label following the cursor rather than the one preceding it. This effect is amplified if the cursor is an instruction (e.g. 'call'), but reversed when the guinea pig just read a verse from the Koran.

CTRL Enter

Go to the definition of the label under the cursor.
If the latter is itself a definition, then we take the next.
If there is no label under the cursor, same selection mechanism than CONTROL- *

fx_dispatch call display3D ; CTRL-ENTER go to 'display3D' whatever the cursor position

To try it is to adopt, as we say in Denmark.

CTRL Return

Back to previous position (after Ctrl Enter). It works on 8 levels.
As I am not dog (*), I give you a mnemonic: "Enter routine", "Return from routine."

(*) Not that dogs be petty, but they seldom write user guides.


Cycle through the last 8 rows changed. Very handy, I find, having wandered in the source to return to where it was.


Paste the last line cut with CTRL-DEL. UNDO serves rustic but also allows you to duplicate a line faster than the blocks. In this case, must be deleted to better re-insert!

CTRL F (Find) (TAB to continue the search)

Text Search.

  • Case insensitive
  • Indifferent to the tabs (unlike TurboAss where you have to enter the exact number of spaces to search mnemonics with operands).
  • By default, exhaustive search.
    • Precede the search string with a space if it is desired to search only at the beginning of words.
    • End the search string with a space if one wishes to look only at the end of words.
    • Surround the search string with spaces if you want exact search for the word alone.
    • In all these cases, the space at the beginning and at the end is not wanted literally, as shown by the following examples.
V Searched / In source -> OR A LD HL,orang LD HL,Cador LD HL,morel + 4
"Or" * * * *
" Or" * *
"Or " * *
" Or " *

Assembler Shortcuts

We reserve CONTROL+number for assembler shortcuts (presumably fewer). This allows:

  1. Expand easier each other without risk of conflict.
  2. From store / used more efficiently (less cognitive interference, to speak like my concierge).

CONTROL-1: Assemble

CONTROL-2: Assemble+jump

CONTROL-4: Go to the next assembly error.

These shortcuts are achievable with one hand, freeing the other to smoke a Cuban.

Program is lunched under DI, standard RAM connection (&C0), SP set to SP C000, with the correct firmware values for AF 'and BC'.


It is pre-assembled.

  • Facilitates the detection of errors when typing.
  • Identification of the label rather than to editing the assembly: essential for super-fast assembly.
  • Much more compact code.
  • Reduces the need for file 'object' (assembled code provided with the information necessary for the relocation and / or to access its routines).
  • There is the possibility to import / export ASCII versions.
  • In the display, imposes breaks (for opcodes / instructions) and Tab. It is also an advantage: uniformity of code without having to format it by hand!

Compiler directives

Org X [,Y]

Or how to generate a Y address of the code to be executed by X.

We distinguish:
* Code pointer (pseudo label $), the address where the code is supposed to run (ie $ almost plays the role of PC)
* Object pointer (pseudo label $$), the address where the code is stored by the assembler.

In the most common scenario, the two coincide, and the ORG X allows to change this address.
Used with two parameters fixed ORG $ and $$ separately.

The following code:

     ORG &1000, &2000
loop JP loop

generate the code C3 00 10 at &2000.

To change $ only:

byte message "Hello dad!", 0
      ORG &C000, $$
     ; the code is stored after post
toto; this label is &C000

To change $$ only:

     ORG $,&4000

Known bugs

Assembled code in &30-&32 is overwritten by JP &BE00 (Breakpoint mechanism).

ALIGN(n) (MACRO example)

Advance $ to the closest multiple of n.
If $ is already a multiple if n, the directive doesn't change anything.

NB: $$ is incremented by the same amount

There is no ALIGN directive. It can be simulated by:

    SKIP -$ MOD n

We want to skip x bytes such that $+x = 0 [n] and 0 <= x < n
This amounts to x = -$ MOD n

ASSERT(predicate) (MACRO example)

Raise an error if predicate isn't true.

There is no ASSERT directive. It can be simulated by:

  MACRO ASSERT predicate
    IF predicate:ELSE
   !! ERROR !!

The '!! ERROR !!' part is not seen at all if predicate is true,
otherwise it triggers an assembly error.

Example 2:

  MACRO ASSERT_NOT predicate
    IF predicate
 !! ERROR !!


  ASSERT_NOT (my_table AND &ff) ; Ensure my_table is &100 aligned


Currently the error line points to the macro definition, not to macro invocation.
That's unconvenient.


No such directive for now, but here is a workaround:

After your code, add:

  SKIP &A000-$  ; To protect overlapping at &A000

If $ if greater than &A000, the value is negative, raise an error.


Directive BANK n re-configures the memory similarly to OUT &7FFF,n.

   BANK &C4
   ORG &3F00
   [...]; &200 bytes of tasty code

generates code both in main RAM and "&C4".


   BANK &C2
   ORG &3F00

generates code both in banks &C4 and &C5.

Known bug!

The connections &C1 and &C3 are poorly managed.


The BYTE command accepts strings and bytes, possibly mixed:

BYTE 12,"ABC",-1 Encodes 0c 41 42 43 ff

A "BYTE" or "WORD" without a value increments pointers ($ and $$) without writing into memory.
Three possible use-cases:

  • Reuse the current value in memory (eg: setting that you want to keep from one run to another, even in the code re-assembling in between).
  • A purpose of documentation, note that the value does not need to be initialized by the assembler (eg: variable anyway initialized at run-time).
  • Easily define positions in a structure. Eg:
         ld a, (ix + pat_flags) Give ld a, (ix + 2)
         ld e, (ix + pat_value) Give ld e, (ix + 3)
         ld d, (ix + pat_value + 1) Give ld d, (ix + 4)

          ORG 0
pat_pos WORD       ; Do not write anything at 0!
pat_flags BYTE
pat_value WORD


Restore the system, the battery, the oil level before returning to the editor.
Thus, no need to save AF 'and BC', the interrupt vector in &38, etc …


  • Automatically detects invalid references
  • No limitation in size (the name of labels being stored once, do not hesitate to choose long)
  • Starts with a letter, followed by letters, numbers, or the following characters "_ #"

Digital Expressions

True management sign

A step = -1 does not encode &ff nor &ffff, but indeed -1. Thus, LD A, step*step passes without worries.
Therefore, an error in an overflow indicates a real problem in your program.

Extended Arithmetic

Labels can take the signed 24-bit values. Authorizes for instance:

ram = &40000; yes, 256k

chunksNb = 16;
chunkSize = ram / chunksNb;

Expressions and temporary results can reach 1024 bits.

   ld, ram*ram / &100000000; ok, it's 16


  • Warning: No operator precedence!

Sequencing is made only by spaces and square brackets.

  • Examples:
     LD,1+2*3; 9 (+ and * made in order)
     LD,1+2 *3; 9
     LD,1+ 2*3; 7 (2 * 3 form an isolated group, calculated separately before adding 1)
     LD 1+[2*3]; 7 Idem, more classic.
  • Simple rule. Nothing to remember. Visually consistent.

Logical operators and modulo in full (and, xor, or, mod)

Easy to remember.


An instruction or a block can be repeated. The advantages are obvious:

  • Compact Plus (to read, write and store)
  • The number of repetitions is controlled by a label.
  • "Defs" on steroids:
     16 ** byte 1,2,3; 1,2,3,1,2,3,1,2,3 ...

For a block repetition, '[' should be on the same line:

; Good
   NbLines ** [
       INC B: OUTI
       INC B: OUTI
       OUT (c),e: OUT (c),d: OUT (c),0
; bad
   NbLines **
     INC B: OUTI
     INC B: OUTI
     OUT (c),e: OUT (c),d: OUT (c),0

Of course, any label within a block repeated more than once will throw an error (double definition).

Expressions are re-evaluated at each iteration. This facilitates the creation of tables:

             ORG &9000
rampe3 256 ** BYTE $*3 and &FF ; stores 00 03 06 09 ... FF 02 05 08 ...


     4 ** LD A, (DE): INC E; buggy. Only 1 E INC
     4 ** [LD A, (DE): INC E]; OK.

It allows up to 8 levels of nesting. For more, request exemption from the nearest clinic.

Pseudo labels #, ##, ###

The pseudo label # is the index to the containing iteration (include from 0).
The pseudo label ## is the index of the iteration at the next level (when several nested repetition, of course).

 2 ** [
 3 ** BYTE &10*## + # ; stores 00 01 02 10 11 12

Separator ":"

  • Used to group instructions that form a logical operation, and to better include the similarities. Eg:
        LD hl, awesomeness: inc (hl)
        LD hl, brightness : inc (hl)
        LD hl, ovlness    : inc (hl)
  • Less line = better overview on a routine.
  • Essential for coming pseudo-labels.

Conditional assembly

Orgams allows 8 levels of IF ELSE END. To consume without moderation, with moderation.




  • d: Go to the last visited address (pointer >)
  • dnn: Visit from nn.


As d, with the following nuance:

  • t: Go to the next opcode to execute (pointer $)
  • tnn: Change PC ($) in order to trace from nn.


  • This corresponds to the DAMS t command.
  • t is equivalent to d then CLR.

m [nn]

Dump memory from nn. If nothing is specified, use the previous address.
The bytes are displayed in hexa, ASCII and graphically. Useful for checking a curve or detecting anomalies.
Zones at 0 are skipped. Thanks WHO ?

xnn, nn2

Compare two memory areas. Only the differences are displayed.
So, for example, to compare banks & c6 and & c7:

b & c2
x & 8000, & c000

hnn, size

Injects 'size' bytes from 'nn' into the source as BYTE.


Graphic memory dump.
Attention unlike the Hacker, we do not get 1 non-zero byte = 1 pixel put.
The bytes are roughly ORed in packets of 8.

clear [n] / clr [n]

Filled the first 128 kb with n or 0, regardless of the current connection.

clearpage [n] / clp [n]

Fill the connected page (64 ko) with n or 0.


ROM installs to reset a breakpoint routine &BE00, and a jump to &30 in this routine.


Use RST 6 to jump into the monitor in trace mode. Identically, the pseudo BRK instruction (CTRL + SPACE) in the source simply puts RST 6, which jumps to &be00.
Using &BE00 facilitates conditional breakpoint. Eg:

break = &BE00
    LD (pattern_pos) ; Must be non-zero
    OR a
    CALL z,break; Investigate!

All registers at the time of the judgment are preserved. The only destructive manipulation is writing two words in the stack:

  1. The return address placed by the RST (or CALL &BE00), necessary to know the current PC.
  2. One PUSH AF necessary to probe IFF (state EI / DI).

In conventional use, this does not disturb the return to the program (like an interrupt). But if SP pointed to a table, it will take account of the corruption of 4 bytes.

Make sure you restore the RAM banks before using BRK!
Example trap:

   LD BC, &7fC2
   OUT (C), C
   BRK; Crash !! Jumps to &30 in the wrong bank.

Soft BreakPoint.

Using the quick trace allows to break without modifying the code (in ROM for example).

  • $start to place the PC on the code to be executed. Leave the trace with ESC.
  • dbreak to move to the breakpoint address, then space or t (quick trace until $ reaches >).

For example, if the entry of your program is &9000 and you want to interrupt at &BB5A:

  • $&9000, ESC, d&bb5A, space.

For this case it may be more efficient to modify the source:

   ORG &9000:ENT $

But then &BB5A is trashed!

Debugger / disassembler.

There are two types of navigation, with or without execution. Besides, the command 'of the monitor can be understood (D)ebug or (D)isassemble.

Without enforcement, this is a classic disassembly, but with all the flexibility Orgams (kiss your lap):

  • Up and down scrolling (fast with CONTROL)
  • CONTROL-ENTER and RETURN like the editor to explore subroutines (and back!) Without having to enter a single address.

With execution include all the power of a debugger step by step:

  • (S)tep executes an instruction. If there is a call, it enters the subroutine.
  • (N)ext running in fast mode
  • Sometimes you neither want to trace nor execute a routine (eg &BB06). In this case, simply move the pointer to the next instruction, and fingers enable CONTROL-G. This changes PC ($) without executing anything.
  • To avoid having to painstakingly follow the N iterations of a loop, it will place the cursor appropriately, and then build on T or SPACE: the loop will be well executed, but in fast mode.


  • The bit 3 & 5 of the register F are not reproduced correctly.
  • Interruptions are not emulated.

Source/Memory visualization

Orgams try to find source line matching the opcode under cursor '>'. It can fail, rightly or wrongly, thus displaying "source not found". This feature slow down step-by-step trace, mostly in case of failure.
Kindly press CONTROL-V switch to memory dump, to last address selected via 'M' command in monitor. This mode doesn't penalize trace's speed.

Back to source

CONTROL-ESC returns to editor at currently visualized line, contrarily to ESC-ESC which leaves editor cursor untouched.

Back to the program.

Return by pressing J (like 'J'UMP). The state of the Z80 is restored: the point of view of registers it is as if we had called the routine PUSH AF: POP AF: RET. Of course if the program was not traced by step was taken with the current values of registers.
The CRTC registers are restored with the system defaults.

Known Issues

These are the known issues for Demomaker's Delight releases.
For new bugs in current beta, see Regression section in working.
Go to bugs for complete description.

#106 BRK doesn't always capture right bank connection (MMR). (FIXED with Multiface2 in EE BETA I)
#105b BRK doesn't capture ROM connection selected via VGA.
#105a BRK doesn't capture ROM connection selected via firmware. (FIXED IN EE BETA J)
#104b R register not properly restored after breakpoint. (FIXED IN EE BETA J)
#104a R register not properly captured at break time. (FIXED IN EE BETA I)
#FA [Editor] Import may hang/crash when trying to import raw binary instead of text.
#F8 [Editor] Modification lost when reset.
#F5 [Editor] CONTROL-ENTER does not work for macro parameters
#EF [Monagams] Wrong evaluation order of parameters.
#E9 [Assembler] # outside [ ] might corrupt the source. (FIXED IN CURRENT EE BETA)
#E6 [Assembler/Begnin] Cannot jr from FFxx to 00xx
#E5 [Editor] COPY doesn't behave as a real dead key.
#E2 [Orgams] Breakpoint reinstalled when met or when returning from exec.
#E1 [Assembler] Should warn in case of memory conflict.
#DF [Trace] ROM connection not detected at BRK point.
#DA [Orgams] Bank directive not honored for binary save.
#D4 [Assembler] MACRO/ENDM and IF/END interleaving not supported.
#C2 [Assemblage] Code assembled in &BFCC-&BFFF is overwritten.
#C0 [Trace] Visualisation: Wrong line source when using conditional assembling.
#BB [Editeur] very low priority 'DEFS n' from DAMS source not correctly imported.
#BA [Editeur] Wrong error message instead of "memory full" when importing.
#B7 [Trace] $ not shown if in middle of instruction.
#A9 [Assembler] Overlapping output should raise error.
#A8 [Assembler] Two ENT directives should raise error.
#A6 [Editor/Parser] Parsing too slow
#A4 [Trace] When entering trace screen, navigation history shouldn't be reset.
#94 [Assembleur] Code assemblé écrasé par gestion Jump.
#93 [Assembleur] Code assemblé écrasé par breakpoint.
#90 [Orgams] |O,"file" ne marche pas quand HIMEM en &4000-&7FFF
#5D [Assembleur] 'IF' consistency not checked.
#4D [Trace] CONTROL-ENTER not working for RSTs
#45 [Monogams] Dummy value pour non-defined labels.
#44 [Monogams] ?1/0 renvoie #1ff
#1B [Madram] Parser. LD A,1 + 1 not recognized.
#15 [Assembleur] BUG LD A,"AA"
#05 [Trace] Crash when tracing trace

Sauf mention contraire, le contenu de cette page est protégé par la licence Creative Commons Attribution-ShareAlike 3.0 License