MEG-4 User's Manual

Welcome to the manual for the MEG-4, the Free and Open Source virtual fantasy console.

Getting Started

In Your Browser

If you don't want to install anything, just visit the website, it has an emulator running in your browser.

Installing

Go to the repository and download the archive for your operating system.

Windows

1. download meg4-i686-win-sdl.zip
2. extract it to C:\Program Files directory and enjoy!

This is a portable executable, no actual installation required.

Linux

1. download meg4-x86_64-linux-sdl.tgz
2. extract it to the /usr directory and enjoy!

Alternatively you can download the deb version for Ubuntu or RaspiOS and install that with

sudo dpkg -i meg4_*.deb

Running

When you run the MEG-4 emulator, your machine's localization will be autodetected, and if possible, the emulator will greet you in your own language. The first screen it will show you is the "MEG-4 Floppy Drive" screen.

Just drag'n'drop a floppy file onto the drive, or left click on the drive to open the file selector. These floppies are PNG images with additional data, and an empty one looks like this:

Other formats are supported too, see file formats for more details on what else can be imported. Once your floppy is loaded, the screen will automatically change to the game screen.

Alternatively you can also press Esc here to get to the editor screens and start creating contents from ground up.

Command Line Options

On Windows, replace - with / for the flags (because that's the Windows' way of specifying flags, for example /n, /vv), otherwise all options are identical.

Use right-click on meg4.exe, and from the popup menu select Create shortcut. Then right-click on the newly created shortcut file, and from the popup menu choose Properties.

meg4 [-L <xx>] [-z] [-n] [-v|-vv] [-s] [-d <dir>] [floppy]

File Formats

Although the built-in editors are pretty awesome, MEG-4 is capable of handling various file formats both on export and import side to ease creation of content, and make the use of MEG-4 actual fun.

Floppies

MEG-4 stores programs in "floppies". These are image files that look like a real floppy disk. You can save in this format by pressing Ctrl+S, or by selecting > Save from the menu (see interface). You'll be prompted to give a label to the floppy, which will be your program's title as well. To load such floppies, press Ctrl+L, or just simply drag'n'drop these image files onto the MEG-4 Floppy Drive.

The low level specification for this format can be found here.

Project Format

For convenience, there's also a project format, which is a zip archive containing the console's data in only common and well-known formats so that you can use your favourite editor or tool to modify them. You can save in this format by selecting the > Export ZIP menu option. To load, you can simply drag'n'drop such zip files into the MEG-4 Floppy Drive.

Files in the archive:

metainfo.txt

A plain text file with the MEG-4 firmware version and the program's title.

program.X

Your program's source code, created in the code editor, as a plain text file. You can use any text editor to modify. On export, newlines are replaced with CRLF for Windows compatibility, on import it doesn't matter if lines are ended with NL or with CRLF, both supported.

The source code must start with a special first line, a #! shebang followed by the programming language used. For example #!c or #!lua. This language code must also match the extension in the file name, eg: program.c or program.lua.

sprites.png

A 256 x 256 pixels indexed PNG file, containing the 256 colors palette and all of the 1024 sprites, each 8 x 8 pixels, created in the sprite editor. This image file is editable by GrafX2, GIMP, Paint etc. On import, true color images will be converted to the default MEG-4 palette using the smallest weighted sRGB distance method. This works, but not looking particularly good, therefore it is recommended to save and import paletted PNG images instead. Sprites can also be imported from Truevision TARGA (.tga) images, if they are indexed and have the correct dimensions of 256 x 256 pixels.

map.tmx

The map, created in the map editor, in a format that can be used with the Tiled MapEditor. Only CSV encoded .tmx is generated, but on import base64 encoded and compressed .tmx files can be loaded too (everything except zstd). Furthermore PNG or TARGA images are supported on import too, provided they are indexed and their dimensions match the required 320 x 200 pixels. The palette in these images aren't used, except the spritebank selector is stored in the first entry (index 0) alpha channel.

font.bdf

The font, created with the font editor, in a format that can be edited by many tools, like xmbdfed or gbdfed. Obviously I'd recommend my SFNEdit instead, and FontForge works prefectly too. On import, besides of X11 Bitmap Distribution Format (.bdf), PC Screen Font 2 (.psfu, .psf2), Scalable Screen Font (.sfn) and FontForge's native SplineFontDB (.sfd, bitmap variant only) supported too.

sounds.mod

The sound effects you created in the editor in Amiga MOD format. See music below. The song must be named MEG-4 SFX.

All 31 waveforms are stored in this file, and only the first pattern used, and only one channel (64 notes in total).

musicXX.mod

The music tracks you created in the editor in Amiga MOD format. The XX number in the file name is a two digit hexadecimal number, which represents the track number (from 00 to 07). The song must be named MEG-4 TRACKXX, where XX must be the same hexadecimal number as in the filename. There are dozens of third party programs to edit these files, just google "music tracker", for example MilkyTracker or OpenMPT, but for a true retro feeling, I'd recommend the moderized clone of FastTracker II, available for both Linux and Windows.

From music files, only those waveforms are loaded that are referenced from the notes.

You can find a huge database of downloadable Amiga MOD files at modarchive.org. But not all files are actually in .mod format on that site (some are .xm, .it or .s3m etc.); you'll have to load those in a tracker and save them as a .mod first.

Music can also be imported from MIDI files, but these files only store the musical note sheet, and not the waveforms like Amiga MOD files do. General MIDI Patch has standardized the instrument codes though, and MEG-4 has some built-in wavepatterns for these, but due to size constraints those are not the best quality, so importing your own wavepatterns with MIDI files is strongly recommended.

memXX.txt

Hexdump of the memory overlays data (which are binary blobs by nature). Here XX is a hexadecimal number from 00 to FF. The format is the same as hexdump -C's, you can edit these with a text editor. On import, binary files by the name memXX.bin also supported. For example, if you want to embed a file into your MEG-4 program, then name it mem00.bin, drap'n'drop it into the emulator, and afterwards you'll be able to load it in your program with the memload function.

Other Formats

Normally waveforms are automatically loaded from Amiga MOD files, but you can also individually import and export wave patterns in .wav (RIFF Wave 44100 Hz, 8-bit, mono) format. These are editable with Audacity for example. If the imported file is named as dspXX.wav, where XX is a hexadecimal number between 01 and 1F, then the waveform is loaded at that position, otherwise at the first empty slot.

You can import MEG-4 Color Themes from "GIMP Palette" files. These are simple text files with a little header, and in each line red, green and blue numeric values. Each color entry line defines the color of a specific UI element, see the default theme src/misc/theme.gpl for an example. Theme files can also be edited visually using GIMP or Gpick programs too.

Furthermore, you can import PICO-8 cartridges (both in .p8 and .p8.png formats) and TIC-80 cartridges (both in .tic and .tic.png formats), however you'll have to adjust the imported source code, because their memory layouts and API calls are different to MEG-4's. But at least you'll get their assets properly. The TIC-80 project format isn't supported because those files are unidentifiable. If you really want to import such a file, then first you'll have to convert it using the prj2tic tool, which can be found in the TIC-80 source repo.

Exporting into these cartridges is not possible, because the MEG-4 is lot more featureful than the competition. There's simply no place for all the MEG-4 features in those files.

User Input

Gamepad

The first gamepad's buttons and joysticks are mapped to the keyboard, they are working simultaniously. For example it doesn't matter if you press Ⓧ on the controller, or X on the keyboard, in both case both gamepad button flag and keyboard state flag will be set. The mapping can be changed by writing the keyboard scancodes to MEG-4's memory, see memory map for details. The default mapping goes like cursor arrows are the directions ◁, △, ▽, ▷; the Space is the primary button Ⓐ, C is the secondary button Ⓑ and X is Ⓧ, Z is Ⓨ. The Konami Code is working too (see KEY_CHEAT scancode).

Pointer

Coordinates and button pressed states can be easily accessed from the MEG-4's memory. Scrolling (both vertical and if supported, horizontal) handled as if your mouse had up / down or left / right buttons.

Keyboard

For convenience, it has several shortcuts and multiple input methods.

Key Combination	Description
GUI	Or Super, sometimes has a logo on it. UNICODE codepoint input mode.
AltGr	The Alt key right to the space key, activates Compose mode.
Alt+U	In case your keyboard lacks the GUI key, UNICODE input mode too.
Alt+Space	Fallback Compose, for keyboards without the AltGr key.
Alt+I	Enter icon (emoticons) input mode.
Alt+K	Enter Katakana input mode.
Alt+J	Enter Hiragana input mode.
Alt+A	For keyboards without such key, works as a & key (ampersand).
Alt+H	For keyboards without such key, works as a # key (hashmark).
Alt+S	For keyboards without such key, works as a $ key (dollar).
Alt+L	For keyboards without such key, works as a £ key (pound).
Alt+E	For keyboards without such key, works as a € key (euro).
Alt+R	For keyboards without such key, works as a ₹ key (rupee).
Alt+Y	For keyboards without such key, works as a ¥ key (yen).
Alt+N	For keyboards without such key, works as a 元 key (yuan).
Alt+B	For keyboards without such key, works as a ₿ key (bitcoin).
Ctrl+S	Save floppy.
Ctrl+L	Load floppy.
Ctrl+R	Run your program.
Ctrl+⏎Enter	Toggle fullscreen mode.
Ctrl+A	Select all.
Ctrl+I	Invert selection.
Ctrl+X	Cut, copy to clipboard and delete.
Ctrl+C	Copy to clipboard.
Ctrl+V	Paste from clipboard.
Ctrl+Z	Undo.
Ctrl+Y	Redo.
F1	Built-in help pages (the API Reference in this manual, see interface).
F2	Code Editor
F3	Sprite Editor
F4	Map Editor
F5	Font Editor
F6	Sound Effects
F7	Music Tracks
F8	Memory Overlays Editor
F9	Visual Editor
F10	Debugger
F11	Toggle fullscreen mode.
F12	Save screen as meg4_scr_(unix timestamp).png.

UNICODE Codepoint Mode

In this mode you can enter hex numbers (0 to 9 and A to F). Instead of these separately pressed keys, the codepoint they describe will be added as if your keyboard had that key. For example the sequence GUI, 2, e, ⏎Enter will add a . dot, because codepoint U+0002E is the . dot character.

This mode automatically quits after the characterer is entered.

Compose Mode

In compose mode you can add acute, umlaut, tilde etc. to the characters. For example the sequence AltGr, a, ' will add á, or AltGr, s, s will add ß, and another example, AltGr, c, , will add ç, etc. You can use Shift in combination with the letter to get the uppercase variants.

This mode automatically quits after the characterer is entered.

Icon Mode

In icon mode you can add special icon characters, representing the emulator's input (like the sequence Alt+I, m will add the 🖱 mouse icon, and Alt+I, a will add the icon of the gamepad's Ⓐ button) as well as emoji icons (like Alt+I, ;, ) will add the character 😉, or Alt+I, <, 3 will produce ❤).

This mode remains active after the characterer is entered, press Esc to return to normal input mode.

Katakana and Hiragana Modes

Similar to icon mode, but here you can type the Romaji letters of pronounced sound to get the character. For example the sequence Alt+K, n, a, n, i, k, a is interpreted as three sounds, and therefore will add the three characters ナニヵ. Also, punctation works as expected, for example Alt+K, . will produce Japanese full stop character 。.

You can use Shift in combination with the first letter to get the uppercase variants, for example Alt+K, Shift+s, u will produce ス and not ㇲ.

This mode remains active after the characterer is entered, press Esc to return to normal input mode.

Interface

Game Screen

By default, you'll see the game screen, with your game running (or the MEG-4 Floppy Drive if there's no game loaded). When you press Esc on this screen, then you'll switch to editor mode.

Editor Screens

If you press Esc (no re-compilation) or Ctrl+R (re-compiles your program) in any of the editor modes then you'll return to the game screen.

All editors are themable, to recolor the entire interface, just drag'n'drop a GIMP Palette file into the screen. See other formats for details.

All editors have a menu on the top. By clicking on the icon, a pop up menu will appear, from where you can access various functions, most of which also accessible through keyboard shortcuts (see keyboard). You can also access the built-in help pages from here, however that's always accessible in all editors by pressing F1 too.

Help Pages

On the help pages screen, you can click on the links, and you can also press Backspace to return to the previous help page in history. If the history is empty, then this will return to the Table of Contents page. The help screen is the exception to the rule, because pressing Esc here does not always return to the game screen, instead it returns to the screen where it was invoked from.

To start a search, you can click on the search input box on the top right, or just start typing what you're looking for.

The built-in help pages reader is actually a very minimal MarkDown viewer, and it shows exactly the same info that were used to generate this manual (but this manual you're reading now has more sections, the built-in one is limited to the API Reference).

Code Editor

Click on the pencil icon (or press F2) to write your program's source code.

Code has three sub-pages, one where you can write the source code (this one), the Visual Editor, where you can do the same using structograms, and your program's machine code can be seen in the debugger.

Here the entire area is one big input field for the source code. At the bottom, you can see the status bar, with the current's row and coloumn, the UNICODE codepoint of the character under the cursor, and if you're standing in an API's argument list, a quick help on that API function's parameters (suitable for all programming languages).

Programming Language

The program must start with a special line, with the characters #! followed by the language you want to use. By default, it uses MEG-4 C (a subset of ANSI C), but you can choose others as well. See the list under "Programming" in the table of contents on the left.

User Provided Functions

Regardless to the scripting language you choose, there are two functions that you should implement. They have no arguments and they return no value.

• setup function is optional and runs only once when your program gets loaded.
• loop function is mandatory, and runs every time a frame is generated. At 60 FPS this means a 16.6 msecs timeframe, but the MEG-4 "hardware" itself takes about 2-3 msecs, which leaves you a 12-13 msecs for your function to fill. You can query this value from the performance counter MMIO register, see memory map. If it takes longer to run the loop function, then the screen might became laggy, and the emulator will be less responsive than usual.

Additional Shortcuts

In addition to standard keyboard shortcuts and input methods (see keyboard), these work too in the code editor:

From the menu, you can also access Find, Replace, Go to, Undo, Redo as well as the list of bookmarks and the defined functions.

Sprite Editor

Click on the stamp icon (or press F3) to modify the sprites.

The sprites you create here can be displayed using spr, and also used by dlg to generate a dialog window and by stext when it displays text on screen.

The editor has three main boxes, two on the top, and one below.

Sprite Editor Box

The one on the left is the sprite editor box. This is where you can draw to modify the sprite. places the selected pixel on the sprite, clears it to empty.

Sprite Selector

On the right you can see the sprite selector. The sprite you select here will be editable on the left. You can select multiple adjacent sprites and edit them together.

Palette

Below you can see the palette. The first item cannot be set, because that's for erase. If you select any other color, then the palette button will become active. Clicking on it will bring up the HSV color picker, and with that you can modify the color for that palette entry.

The default MEG-4 palette uses 32 colors of the DawnBringer32 palette, 8 grayscale gradients, and 6 x 6 x 6 RGB combinations.

Toolbar

Under the sprite editor, you see the tool buttons. With these you can easily modify the sprite. Shifting in different directions, rotating clock-wise, flipping etc. If there's an active selection, then they operate on the selection only, otherwise on the entire sprite. For the rotation, you must select an area which has the same width as height, otherwise rotation would be impossible.

The flood fill tool only fills adjacent same pixels, unless there's a selection. With a selection the entire selected area is filled, no matter what pixels the selection contains.

Selections

There are two kinds of selections: rectangle selection and fuzzy select. The former selects a rectangular area, the other selects continous regions with the same pixel. You can press and hold Shift to expand the selection, and Ctrl to intersect and make it smaller.

Pressing Ctrl+A will select all, and Ctrl+I will invert the current selection.

When a selection is active, you can press Ctrl+C to copy the area to the clipboard. Later, you can press Ctrl+V to paste it. Pasting works exactly like the pencil tool, except now you can paint with the whole copied area like a brush. It worth noting that empty pixels are copied to. If you don't want your brush to clear the area, then only select non-empty pixels (you can use Ctrl+ to deselect the empty areas) before copy, that way the empty pixels won't be copied to the clipboard, and in return won't be used as part of the brush.

Map Editor

Clicking on the jigsaw icon (or pressing F4) will bring up the map editor. Here you can place sprites as tiles on the map.

The map you've created here (or any parts of it) can be put on screen using the map or with the maze commands (see below).

The map is special in a way that it can only display 256 different tiles at once out of the 1024 sprites. For each sprite bank, the first sprite is always reserved for the empty tile, so sprites 0, 256, 512, and 768 cannot be used on maps.

Map Editor Box

On top the big area is where you can see and edit the maps. It is shown as one big map, 320 columns wide and 200 rows high. You can use the zoom in and zoom out buttons on the toolbar, or the mouse wheel to zoom. By pressing right click and holding it down, you can drag the map, but you can also use the scrollbars on the right and on the bottom.

Clicking with left button will set the selected sprite on the map. Select the first sprite to clear the map ( right click does not clear here, instead it moves the map).

Toolbar

Below the map editor area is the toolbar, same as on the sprite editor page, with exactly the same functionality and same keyboard shortcuts (but it can use sprite patterns too, see below). Next to the tool buttons you can find the zoom buttons and the map selector. This latter selects which sprite bank is used on the map (just for the editor. When your game runs, you'll have to set the byte at offset 0007F to change the map's sprite bank, see Graphics Processing Unit).

Sprite Palette

On the right to the buttons is the sprite selector, where you can select the sprite you want to draw with. As said earlier, the first sprite in every 256 sprites bank is unusable, reserved to the empty map tile.

The difference to the sprite editor is (where you can choose just one color from the palette), here on the map you can select multiple adjacent sprites at once. With paint, all of them will be painted at once (exactly the same way as if they were pasted from the clipboard), and what's more, flood fill will use them as a brush too, filling the selected area with that multi-sprite pattern.

Even more, clicking Shift+ with the fill tool, it will choose one sprite from the pattern randomly. For example, let's assume you have 4 sprites with different looking trees. If you select all of them and fill an area on the map, then those sprites will be placed always in the same order, repeating one after another, which isn't looking good for a forest. But if you press and hold down Shift during clicking with the fill tool, then each tile will be choosen randomly from those selected 4 tree sprites, which looks much more a real forest.

3D Maze

You can also display the map as a 3D maze with the maze function. For this, the turtle position and direction is used as the player's view point to the maze, but to accomodate sub-tile positions, here the turtle's coordinate is multiplied by 128 (originally I've used 8 to match pixels on the map, but movement was too blocky that way). So for example (64,64) is the centre of the top left field on the map, and (320,192) is the centre of the third coloumn and second row.

Here scale parameter acts differently too: when set to 0, then the maze will use 32 x 8 tiles as seen on the sprite palette, one for each tile, each 8 x 8 pixels in size. When set to 1, then there will be 16 x 16 tiles, each tile will use 2 x 2 sprites, so 16 x 16 pixels in size. With 3, you'll have 4 x 4 kinds of tiles, so 16 different tiles in total, each 64 x 64 pixels. In this case the map will select these larger tiles, so tile id only equals with the sprite id if the scale is 0. For example if map has the id of 1 with scale set to 1, then instead of sprite id 1, this will select sprites 2, 3, 34, 35.

Tile id 1 with scale 0          Tile id 1 with scale 1
+---+===+---+---+-              +---+---+===+===+-
|  0|::1|  2|  3| ...           |  0|  1|::2|::3| ...
+---+===+---+---+-              +---+---+===+===+-
| 32| 33| 34| 35| ...           | 32| 33|:34|:35| ...
+---+---+---+---+-              +---+---+===+===+-

Regardless you'll have to place sprite id 1 on the map from the palette to get these sprites. Tile id 0 as usual means empty.

If sky is set, then that tile will be displayed as a ceiling to the maze. On the other hand, grd is only displayed as floor where the map is empty. When you call the maze, you separate the tile ids into ranges, and this specifies how a tile is displayed (floor, wall or sprite). Everything greater than or equal to wall will be non-walkable and displayed as a cube, with the selected tile sprites on the cube's sides without transparency. Tiles greater than or equal to obj will be non-walkable too, but displayed as a properly scaled 2D sprite always facing towards the player (the turtle's position) and with alpha channel applied, so unlike the walls the objects can be transparent.

You can also add non-player characters (or other objects) to the maze independently to the map (in an int array with x, y, tile id triplets, where the coordinates are multiplied by 128). These will be walkable and will be displayed the same as object sprites; collision detection, movement and all the other aspects have to be implemented in your game by you. The maze command just diplays these. It does a favour for you though, if the given NPC can directly see the player, then the tile id's most significant 4 bits in the array will be set. Which bits depends on their distance to each other: the most significant bit (0x80000000) is set if their distance is smaller than 8 map fields, next bit (0x40000000) if less than 4 fields, next bit (0x20000000) if less than 2 map fields, and finally last bit (0x10000000) if they are on the same field or neightbouring map fields.

Furthermore this command also takes care of navigation in the maze, ▴ / △ moves the turtle forward, ▾ / ▽ backward; ◂ / ◁ turns left, and ▸ / ▷ turns right (keyboard mappings for the gamepad can be changed, see memory map for details). Handling all the other gamepad buttons and interactions are up to you to code in your game, the maze only helps you with moving the player and handling collisions with the walls.

Font Editor

Click on the letter icon (or press F5) to modify the fonts.

This font will be used by width when you measure a string, and also by text when you display text from your program.

This page has a similar arrangement as the sprite editor. On the left you can find the glyph editor area, and on the right the glyph selector. (Glyph is the displayed typeface of a UNICODE character.)

Glyph Editor

It is as simple as left clicking sets typeface (foreground), and clears to empty (background).

Glyph Selector

You can search for a UNICODE codepoint, but if you press a key, the glyph selector will jump to its glyph. If your keyboard layout lacks some keys, you can use one of the special input modes, see keyboard.

Toolbar

The toolbar here is limited, only shifting, rotating and flipping allowed, there are no selection tools. However copy (Ctrl+C) and paste (Ctrl+V) works as usual on the glyph selector table.

Sound Effects

Click on the speaker icon (or press F6) to bring up the sound effects editor.

You can play these sound effects from your program using the sfx command.

On the left, you'll see the waveform editor and its toolbar, on the right the effect selector, and below the effect editor.

Effect Selector

On the right you see the list of effects, each represented by a music note (technically all sound effects are music notes, with selectable waveforms and special effects option). Clicking on this list will edit that effect.

Effect Editor

The piano at the bottom, looks like and works like the note editor on the music tracks, except it has less options selectable. You can find further info there, including the keyboard layout.

Waveform Toolbar

Normally the waveform is read-only, and you'll only see what wave the sound effect uses. You'll have to click on the button with the lock icon to make it editable (but first, make sure your sound effect actually has a waveform choosen).

When the toolbar is unlocked, then clicking on the wave will change it.

Using the toolbar you can change the finetuning value (-8 to 7), the volume (0 to 64) and the repeat interval. If you click on the repeat button, then it will remain pressed, and you can select a loop range on the waveform. The wave will be played first through, then it will jump to the beginning of the selected range, and it will repeat that range infinitely.

For convenience, you have 4 default wave generator buttons, one to load the default pattern (the one that General MIDI uses) from the soundfont for this wave and various tools to set the length, rotate, enlarge, shrink, negate, flip etc. the wave. The button before the last will continously play it using its current configuration (even if no loop range defined).

Finally the last button, the Export will export the sample in RIFF Wave format. You can edit this with a third party tool, and to load it back, just drag'n'drop the modified file to the MEG-4 screen.

Music Tracks

Click on the music note icon (or press F7) to edit the music tracks.

The music you create here can be played in your program using the music command.

You'll see five coloumns and below a piano.

Tracks

On the left the first coloumn selects which music track to edit.

Below the track selector you can see the DSP status registers, but this block only comes alive when music playback is on.

Channels

Next to it, you'll see four similar coloumns, each with notes. These are the 4 channels that the music can simultaniously play. This is similar to standard music sheets, for more info read the General MIDI section below.

Note Editor

Under the channels you can see the note editor, with some buttons on the left and a big piano on the right.

Notes have three parts, the first one (on the top in the editor), the pitch consist of further three sub-parts: the note itself, like C or D. Then the - character if it's a flat note, or # for sharp notes. The third part is simply the octave, from 0 (lowest pitch) to 7 (highest pitch). The 440 Hz pitch for the standard musical note A for example is therefore written as A-4. Using the piano you can easily select the pitch.

After the pitch comes the aforementioned instrument (the middle part of the note) that chooses the waveform to be used, from 01 to 1F. The value 0 is printed as .. and means keep using the same waveform as before.

Finally, you can also add special effects to the notes (the last part of the note), like arpeggio (make it sound like a chord), portamento, vibrato, tremolo etc. See the memory map for a full list. This has a numeric parameter, usually interpreted as "how much". It is printed as three hex numbers, where the first represents the effect type and the last two are the parameter, or ... if it's not set. For example C00 means set the volume to zero, so silence the channel.

Keyboard

1. wave selectors
2. effect selectors
3. octave selectors
4. piano keyboard

It is important to mention that not all features have a keyboard shortcut. For example you might have 31 wavepatterns, but only the first 20 have shortcuts. Similarily, there are several magnitudes more effects than what's accessible through shortcuts.

General MIDI

You can import music (at least the note sheets) from MIDI files. Very simply put, if a classic music note sheet is stored on a computer in a digitalized form, then it is using the MIDI format to do so. Now these are suitable from a single instrument to a huge orchestra, so they can store a lot more than what the MEG-4 is capable of, therefore

Before we could continue, we must talk about the terms, because unfortunately both the MIDI specification and the MEG-4 uses the same nomenclature - but for totally different things.

• MIDI song: a single .mid file (SMF2 format not supported).
• MIDI track: one row on a classic music notes sheet.
• MIDI channel: only exists because MIDI was created by morons, who thought it is fun to squash everything into a single track when storing in files, otherwise exactly the same as a track. You have 16 of these.
• MIDI instrument: a code (standardized by the General MIDI Patch), which describes the instrument a particular channel is using (except when that's channel 10, don't even ask), you have 128 of these instrument codes.
• MIDI note: one note in the range C on octave -1 to G on octave 9, 128 different notes in total.
• MIDI concurrent notes: the number of notes that can be played at once at any given time. There are 16 channels and 128 notes in MIDI, so this is 2048.
• MEG-4 track: a song, you can have 8 of these.
• MEG-4 sample: a wavepattern stored as a series of PCM samples, analogous to instrument, you have 31 of these.
• MEG-4 channel: the number of concurrent notes that can be played at once at any given time, this is 4.
• MEG-4 note: one note in the range C on octave 0 to B on octave 7, 96 different notes in total.

To avoid confusion, hereafter we'll talk about one MEG-4 track only, and "track" will refer to MIDI channels, and "channel" will refer to MEG-4 channels.

Instruments

Concerning instruments, in total there are 16 families with 8 instruments in each. MEG-4 doesn't have 128 wave banks, so best it can do is, assigning two wavepatterns per family (families 15 and 16 are for sound effects):

In short, the General MIDI instrument will become the (patch - 1) / 4 + 1th wave in the soundfont.

Note that MEG-4 assigns waves dynamically, so these number mean the soundfont's wave number. For example if your MIDI file uses two instruments only, let's say Grand Piano and Electric Guitar, then piano would be assigned wave 1, and guitar wave 2. You can load all waves apriori from the soundfont in the sound effects editor, and then your imported MIDI file will use exactly these wave numbers.

Patterns

The MEG-4 patterns are analogous to classic music note sheets, but while on a classic sheet time goes from left to right and each MIDI track is tied to an instrument, in MEG-4 the time goes from top to bottom, and you can dynamically assign which waveform to use on a particular channel. Consider the following example (taken from the General MIDI specification):

On the left we have three tracks, Electric Piano 2, Harp and Bassoon. The first notes to be played are on the bassoon, right two notes at the same time. Note the bass key on the 3rd track, so these are notes C on octave 3 and C on octave 4, and they both last 4 quoter-notes, so whole notes.

On the right you can see the MEG-4 pattern equivalent. The first row describes these two notes played on a bassoon: C-3 on the first channel, and C-4 on the second. The sample 12 (hex, provided that you have manually loaded the soundfont apriori, otherwise the number would be different) selects the oboe waveform, which isn't exactly a bassoon, but that's the closest we have in the soundfont. The C30 part means the velocity at which these notes are played, which is analogous to the volume (the harder you hit a key on the piano, the louder its sound will be). MEG-4 note volumes go from 0 (silence) to 64 (40 in hex, full volume). So 30 in hex means 75% of the full volume.

The next note to be played is on the harp, starts a quoter-note later than the bassoon, it is a G on octave 4 and lasts 3 quoter-notes long. On the MEG-4 pattern you can see this as G-4 in the fourth row (because it starts at that time), and since channels 1 and 2 are still playing the bassoon, it is played on channel 3. If we were to put this on channel 1 or 2, then the previously played note on that channel would be silenced and replaced by this new one. The sample here is 0C (hex), which is Orchestral Harp.

The last note is on the first MIDI track, which starts half a note later from the start, is an E on octave 5, and lasts 2 quoter-notes, or with other words a half-note long. Because it starts half a note from the start, you can see E-5 in the 8th row, and since we already have 3 notes to be played, so it is assigned to channel 4. The sample 02 selects the waveform for Electric Piano, which isn't the same as MIDI Electric Piano 2, but pretty close.

Now we have two whole long notes, one half and a quoter long and another half note long; started at the beginning, quoter and half note later in this order. This means they all must end at the same time. You can see this in the 16th (or 10 in hex) row, all channels have a C00, "set volume to 0" command.

Tempo

MIDI silently assumes 120 BPM and defines a divisor to quoter-notes. Then it might also define the length of a quoter-note in milliseconds, or not. The point is, it is very complex, and not all combinations can be translated to MEG-4 properly. I've written the importer in a way to discard accumulating rounding errors, and only care about the same relative delta times between two consecutive notes. This way the MEG-4 song's tempo never will be exactly the same as the MIDI song's, but it should sound similar and should never deviate too much either.

The tempo on the MEG-4 is much simpler. You have a fixed 3000 ticks per minute, and the default tempo is 6 ticks per row. This means to achive 125 BPM using the default tempo, you should put notes in every 4th rows (because 3000 / 6 / 4 = 125). If you set the tempo (see effect Fxx) to half of that, 3 ticks per row, then each row will last half the time, therefore you'll get 250 BPM if you were using every 4th row. To get 125 BPM with tempo 3, you would have to use every 8th rows. If you set the tempo to 12, then each row will last twice the time, therefore every 4th row will get you 62.5 BPM, and you'd have to use every 2nd rows for 125 BPM. Hope this makes sense to you.

This only sets when a note should be started to play, and totally independent of how long that sound lasts. For the latter you should use a new note on the same channel, or you should use a C00 "set volume to 0" effect in the row when you want the note to be cut off. If you change the tempo in between, that won't influence the sound played, just how long it's played (because the row to turn it off would now reached at a different time).

Now notes will stop playing too if their wavepattern ends. When that happens, depends on the pitch and the number of samples in the wavepattern (playing at C-4 requires 882 samples of the wave to be sent to the speaker on every ticks). There's a trick here: you can set a so called "loop" on the wavepattern, which means after all the samples are played once, the selected region of the wave will be repeated indefinitely (so you'll have to explicitly cut it off, otherwise the sound would really never stop).

Memory Overlays

Click on the RAM icon (or press F8) to modify the memory overlays.

Overlays are very useful, because they allow switching portions of the RAM, so that you can handle more data than what actually fits in the memory. You can use these to dynamically load sprites, maps, fonts or any arbitrary program data in run-time with the memload function.

They have another very useful feature: if you use memsave in your program, then the contents of the overlay will be saved on the user's computer. Next time you call memload, it won't load the overlay's data from your floppy, rather from the user's computer. With this, you can create permanent storage to store high-scores for example.

Overlay Selector

On the top you can see the memory overlays' overview with each overlay's length. The darker entries mean that particular overlay isn't set. You have 256 overlay slots, from 00 to FF.

Overlay Contents

Below the table you can see the hexdump of the overlay's contents (only if a non-empty overlay is selected).

Hexdump is a pretty simple and straightforward format: in the first coloumn you can see the address, which is always dividable by 16. This is followed by the hex representation of 16 bytes at that address, followed by the character representation of the same 16 bytes. That's all to it.

Overlay Menu

On the menu bar, you can specify a memory address and a size, and press on the Save button to store data in the selected overlay. Pressing the Load button will load the contents of the overlay into the specified memory address, but this time the size only specifies the upper limit how much bytes to load.

The Export button will bring up the save file modal, and will allow you to save and modify the binary data with a third party editor. To import a memory overlay back, all you need to do is naming the file memXX.bin, where XX is the number of the overlay you want use, from 00 to FF, and just drag'n'drop that file into the MEG-4's screen.

Visual Editor

Click on the flowchart icon (or press F9) to edit the source code visually using structograms.

Code has three sub-pages, one allows you to edit the source code visually (this one), textual edit can be done in the Code Editor, and your program's machine code can be seen in the debugger.

TODO

Debugger

Click on the ladybug icon (or press F10) to examine your program's machine code.

Code has three sub-pages, one where you can see your program's machine code (this one), the Code Editor where you can write the source code as text, and the Visual Editor, where you can do the same using structograms.

Here you can see how the CPU sees your program. By pressing Space you can do a step by step execution and see the registers and the memory change. Clicking on the Code / Data button in the menu (or pressing the Tab key) will switch between code and data views.

Code View

On the left you can see the callstack. This is used to backtrace function calls. It also displays the corresponding source line where the function was called. This is a link, clicking on it will bring up the Code Editor, positioned at the line in question. The top of the list is always the line which is currently being executed.

On the right is the list of the bytecode instructions in Assembly that the CPU actually executes.

Data View

On the left is the list of your global variables with their actual values.

On the right you can see the stack, which is splitted into separate parts. Everything above the BP register is the argument list to the currently running function, and everything below that but above the SP register is the area for the local variables.

Registers

Independently to which view is active, you can always see the CPU registers at the bottom. With third party languages, only the FLG, TMR and PC registers are available. See mnemonics for more details on each register.

C

If you want to use this language, then start your program with a #!c line.

Example Program

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Description

The default language of the console is MEG-4 C. Despite being a very simple language, it is for somewhat intermediate programmers. If you're a total beginner, then I'd recommend using BASIC instead.

It was created as a deliberately simplified ANSI C to help learning programming. Hence it is limited, not everything is supported that ANSI C expects, but replacing

#!c

with

1
2
3

will make the MEG-4 C source to compile with any standard ANSI C compiler (gcc, clang, tcc etc.).

It has one non-standard keyword, the debug;, which you can place anywhere in your code and will invoke the built-in debugger. After this, you can execute your code step by step, watching what it is doing.

Here comes a gentle introduction to the C language, focusing on what's special in MEG-4 C.

Pre-compiler

Because there's only one source, and system function prototypes are supported out-of-the-box, there's no need for header files. The pre-compiler therefore is limited to simple (non-macro) defines and conditional source code blocks only.

1
2
3
4
5
6
7
8
9
10
11
12

You can use enumerations with the enum keyword, separated by commas and enclosed in curly brackets. Each element will be one bigger than the previous one. These act as if you had multiple rows of defines. For example the following two are identical:

1
2
3

1

It is also possible to assign direct values using the equal sign, for example:

1

Literals

MEG-4 C understands decimal based numbers (either integer or floating point with or without scientific notation). Hexadecimal numbers must be prefixed by 0x, binary by 0b, octal by 0; characters must be surrounded by apostrophes and strings must be enclosed in double quotes:

1
2
3
4
5
6
7
8

Variables

Unlike in BASIC, variables must be declared. You can place these declaration in two places: at the top level, or at the beginning of a function body. The former become global variable (accessible by all functions), while the latter will be a local variable, accessible only to the function where it was declared. Another difference, that global variables can be initialized (a value assigned to them using =), while local variables cannot be, you must explicitly write code to set their values.

A declaration consist of two things: a type and a name. MEG-4 C supports all ANSI C types: char (signed byte), short (signed word), int (signed integer), float (floating point). You might also put unsigned in front of these to make them, well, unsigned. In ANSI C int can be omitted with short, but in MEG-4 you must not use it. So short int isn't a valid type, short in itself is. Furthermore MEG-4 C supports and prefers standard types instead (defined in stdint.h under ANSI C). These have some simple rules: if they are unsigned, then they start with the letter u; then int means integer type, followed by the number of bits they occupy, and finally suffixed by a _t which stands for type. For example, int is the same as int32_t and unsigned short is the same as uint16_t. Examples:

1
2
3
4
5

Unlike in ANSI C, which allows only English letters in variable names, MEG-4 C allows anything that does not start with a number and isn't a keyword. For example, int déjà_vu; is perfectly valid (note how the name contains non-English letters).

Arrays and Pointers

Multiple elements of the same type can be assigned to a single variable, which is called an array. Pointers are special variables that contain a memory address which points to a list of variables of the same type. The similarity between these two isn't a coincidence, but there are subtle differences.

There's no special command for arrays like in BASIC, instead you just specify the number of elements between [ and ] after the name.

1

Referencing an array's value happens similarily, with an index between [ and ]. The index starts at 0, and array bounds are checked. MEG-4 supports up to 4 dimensions.

To declare a pointer, one has to prefix the variable name with a *. Because C does not recognize string type, and strings are actually just bytes one after another in memory, therefore we use char* pointer. This might be strange at first, so MEG-4 C defines the str_t type, but this is actually the same as char*.

Because pointers hold an address, you must give an address as their value (using & returns the address of the variables), and pointers always return an address. In order to get the value at that address, you must de-reference the pointer. You have two options to do this: either prefix it with *, or suffix it with an index between [ and ], just like with arrays. For example the two reference in the second printf are the same:

1
2
3
4
5

You cannot mix pointers with arrays, because that would be ambiguous. For example

1

Operators

In descending order of precedence:

Arithmetic

* / %
+ -

Relational

!= ==
<= >= < >

Logical

!
&&
||

Bitwise

~
&
|
<< >>

Incremental

++ --

1
2

Conditional

?:

Assignment

= *= /= %= += -= ~= &= |= <<= >>=

Unlike other languages, in C the assignment is an operator too. This means they can appear anywhere in an expression, for example a > 0 && (b = 2). That's why assignment is = and logical equal is ==, so that you can use both in the same expression.

There's also the address-of operator, the & which returns the address of a variable. This is usable when the MEG-4 API expects an addr_t address parameter.

Operators are executed in precedence order, for example in 1+2*3 we have two operators, + and *, but * has the higher precedence, therefore first 2*3 is calculated, and then 1+6. That's why the result is 7 and not 9.

Control Flow

Unlike BASIC where the primary way of altering the control flow is defining labels, in C (as being a structured language) you specify blocks of instructions instead. If you want to handle multiple instructions together, then you place them between { and } (but it is possible to put only one instruction in a block).

Like everythig else, the conditionals use such blocks too:

1
2
3
4
5

You can add an else branch, which executes when then the expression is false, but using else is optional.

With multiple possible values, you can use a switch statement. Here each case acts as a label, being choosen depending on the expression's value.

1
2
3
4
5
6

There's a special block, defined by the label default, which matches any value that doesn't have its own case. These blocks are concatenated, so if the control jumps to a case, then that block, and every other blocks after that is executed. In the example above, if a is 1, then two printfs will be called. To stop this from happening, you must use break to exit the switch.

C supports three iteration types: pre-testing loop, post-testing loop and counting loop.

The pre-testing loop checks the conditional expression first, and does not run the iteration body at all if its false.

1
2
3

The post-testing loop runs the iteration body at least once, it checks the condition afterwards, and repeats only if its true.

1
2
3

The counting loop in C is pretty universal. It expects three expressions, in order: initialization, conditional, stepping. Because you can freely define these, it is possible to use multiple variables or whatever expressions you like (not necessarily counting). Example:

1
2
3

This is the same as:

1
2
3
4
5

You can exit the iteration by using the break statement in its body, but with loops you can also use continue, which breaks the execution of the block too, but instead of exiting it continues from the next iteration.

1
2
3
4
5

Functions

You must divide your programs into smaller programs which might be called multiple times, these are called functions. These are declared as return value's type, name, argument list in ( and ) parenthesis, and function body in a { and } block. Two of these, setup and loop has special meaning, see code editor. The C language does not differentiate between subroutines and functions; everything is a function. The only difference is, functions that do not return a value has the return value's type as void.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Functions are simply called from programs by their names, followed by their argument list in parenthesis (the parenthesis is mandatory, even if the argument list is empty). There's no special command and there's no difference in the call if the function returns a value or not.

Returning from a function is done by the return; instruction. If the function has a return value, then you must specify an expression after the return, and that expression's type must be the same as the function's return type. Specifying return (independly if the function has a return value or not) is mandatory.

1
2
3
4
5
6
7
8
9

Provided Functions

The C language has no special commands for input or output; you simply just do MEG-4 API calls for those. The getc returns a character, gets returns a string and you can print out strings with printf.

Under MEG-4 C you use the MEG-4 API exactly as it is specified in this documentation, there are no tricks, no renaming, no suffixes, nor substitutions either.

BASIC

If you want to use this language, then start your program with a #!bas line.

Example Program

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Dialect

BASIC stands for Beginners' All-purpose Symbolic Instruction Code. It was created by John Kemeny in 1963 with the explicit goal to teach students programming with it. The MEG-4 BASIC is a bit more modern than that, it supports all of ANSI X3.60-1978 (ECMA-55) and many featues from ANSI X3.113-1987 (ECMA-116) too, with minor deviations. It allows longer than 2 characters identifiers, and its floating point as well as integer arithmetics are 32 bit. Most important differences: no interactive mode, therefore you don't have to number each instruction any more (you can use labels instead), and all BASIC keywords are case-insensitive as in the specification, but variable and function names are case-sensitive. The MEG-4 API function calls must be in lower-case; as for the rest it is up to you, but those are case-sensitive too (for example APPLE, Apple and apple are three distinct variables).

It has one non-standard keyword, the DEBUG, which you can place anywhere in your code and will invoke the built-in debugger. After this, you can execute your code step by step, watching what it is doing.

Here goes a detailed description with examples, and all differences noted.

Literals

MEG-4 BASIC understands decimal based numbers (either integer or floating point with or without scientific notation). Hexadecimal numbers must be prefixed by $ (not in the specification, but this was usual in Commodore BASIC and pretty much in every other dialects of the '80s) and strings must be enclosed in double quotes:

1
2
3
4
5

Variables

Variables aren't declared, instead the last letter in their name identifies their type. This can be % for integers, $ for strings, and not in the specification, but MEG-4 BASIC accepts ! for bytes and # for double bytes (word). Anything else is interpreted as a floating point variable.

1
2
3
4
5

The conversion between byte, integer and floating point is automatic and fully transparent. However trying to use a string literal in a number variable or storing a number literal in a string variable would reasult in an error (you must explicitly use STR$ and VAL).

When you assign values to variables, the LET command can be omited.

Literals can also be added to your program using the DATA statement, and then can be assigned to variables with the READ command. READ reads in as many data literals as many variables its argument has, and can be called repeatedly. To reset to the first DATA statement where READ reads from, use RESTORE.

1
2
3
4

There are a few special variables, provided by the system. RND returns a floating point random number between 0 and 1, INKEY$ returns the key the user has pressed or an empty string, TIME returns the number of ticks (1/1000th seconds) since power on, and finally NOW% returns the number of elapsed seconds since Jan 1, 1970 midnight in Greenwich Mean Time.

Arrays

Multiple elements of the same type can be assigned to a single variable, which is called an array.

1
2
3

The BASIC specification expects two-dimensional arrays to be handled, but MEG-4 BASIC supports up to 4 dimensions. Array elements can be bytes, integers, numbers or strings. Dynamically resizing arrays with REDIM is not possible, all are statically allocated using DIM. When the size isn't given, one dimension and 10 elements are assumed.

Operators

In descending order of precedence:

Arithmetic

^
* / MOD
+ -

Relational

<> =
<= >= < >

Logical

NOT
AND
OR

There's one non-standard operator, the @ returns the address of a variable. This is usable when the MEG-4 API expects an addr_t address parameter.

Operators are executed in precedence order, for example in 1+2*3 we have two operators, + and *, but * has the higher precedence, therefore first 2*3 is calculated, and then 1+6. That's why the result is 7 and not 9.

Control Flow

The statement END stops control flow (exists your program).

MEG-4 BASIC does not use line numbers any more, instead it supports GOTO with labels, for example:

1
2
3

Conditional jumps use labels too:

1
2

The ON .. GOTO always needs a numerical expression, and chooses the label accordingly, starting from 1 (if the expression is zero or negative, that always jumps to the ELSE label). There's no ON .. GOSUB, because GOSUB does not accept labels in MEG-4 BASIC.

For IF, both numerical and relational expressions are accepted (every non-zero expression considered true), and what's more, multi line IF .. THEN .. ELSE .. END IF blocks are supported too (but no SELECT CASE).

1
2
3
4
5

As an exception, one command is allowed in a single line IF, provided that's a GOTO or an END:

1
2

For iterations, the counting loop checks its condition before the iteration (does not execute the block if the initial value is greater (or less) than the limit), and looks like this:

1
2
3

This FOR .. NEXT is essentially the same as:

1
2
3
4
5
6
7
8
9

The loop variable must be of float type. The STEP is optional (defaults to 1.0), and the expression after that can be a float literal or another float variable. The from and limit both can be more complex expressions, but they too must return a floating point value.

1
2
3

1
2
3
4
5

MEG-4 BASIC has no other kind of loops like C, but if you want a non-counting pre-testing loop, you can do this:

1
2
3
4
5

And instead of a post-testing loop:

1
2
3

Subroutines and Functions

You can divide your programs into smaller programs which might be called multiple times, these are called subroutines. They are defined between SUB and END SUB blocks. Two of these, setup and loop has special meaning, see code editor. As mentioned earlier, in MEG-4 BASIC GOSUB does not accept labels, and that's because here it accepts subroutine names only.

1
2
3
4
5
6
7
8

Control is transferred on GOSUB, and it is returned to the line after GOSUB when END SUB (or the optional RETURN) reached. Subroutines can access global variables and they might have parameters.

1
2
3
4
5
6
7
8
9
10
11
12

Functions are very similar, but they must have a RETURN and their RETURN statement must contain a returned value, same type as identified by the function's name. Functions are simply called from programs by their names, followed by their argument list in parenthesis (the parenthesis is mandatory, even if the argument list is empty). For example:

1
2
3
4
5

Print Statement

PRINT expression [;|,] [expression [;|,] [expression [;|,]]] ...

Prints one or more exporession on screen. If the expressions are separated by ; semi-colon, then tightly one after another. If by , colon, then the output will be splitted into coloumns. Numbers are always prefixed by a space, and if the command ends in an expression (not in ; nor in ,), then a newline character will be printed at the end as well.

Input Statement

INPUT "prompt" [;|,] variable

Prints out prompt, then reads in a value from user and stores it in the given variable. If the prompt and the variable is spearated by a , colon, then it also prints a ? question-mark after the prompt.

Peek and Poke

You can directly access the MEG-4 memory with these commands, even the MMIO area.

variable = PEEK(address)

Reads in the byte at the given address, converts it into a floating point and stores it in the given variable.

For example, to check if the keyboard queue is not empty:

1

POKE address, expression

Calculates the expression, converts it into a byte and stores that byte value at the given address.

For example, to set the palette for color index 1:

1
2
3
4
5
6
7
8

Provided Functions

Some MEG-4 API are provided as system variables, RND (rnd), TIME (time), NOW% (now), and INKEY$ (getc).

Others are provided as commands, INPUT (gets + val), PRINT (printf), PEEK (inb), POKE (outb).

As to comply with ECMA-55, two functions are renamed: SQR (sqrt) and ATN% (atan). All the rest is used as they appear in this documentation, except they are properly suffixed according their return types (for example, str returns a string, so it is called STR$).

Note that ECMA-55 expects that trigonometrical functions use radians by default (with an OPTION command to switch to degrees), however the MEG-4 API always uses degrees, 0 to 359, where 0 is up, and 90 is to the right. That's why the ATN% gets an integer type suffix for example, as it returns degrees in an integer.

Assembly

If you want to use this language, then start your program with a #!asm line.

Example Program

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Description

This isn't an actual programming language. When you compile one of the built-in languages, the compiler generates bytecode that the CPU executes. Assembly is a one-to-one transcription of that bytecode with human-readable textual mnemonics. It has two sections, data and code, both containing a series of labels and instructions. Instructions are mnemonics with an optional parameter.

You can play around and experiment with this if you feel brave.

Literals

Same as MEG-4 C literals.

Variables

There's no such thing as a variable in Assembly. Instead you specify the data section with .data, and just place the data after one of the db (byte), dw (word), di (integer), df (float) instructions. In this stream of data, before the instruction, you can place labels which will hold the address of that data. To load a value in your code section, first you put that label in the accumulator register using ci, and then issue one of the ldb (load byte), ldw (load word), ldi (load integer) or ldf (load float) instructions. If the ldb or ldw instructions has a non-zero argument, then they sign-extend the value to 32 bit.

Control Flow

Everything that you place after the .code keyword will be code. There's no implicit control flow, each instruction is executed one after another; you have to alter the PC (program counter) using one of the jmp (jump), jz (jump if zero), jnz (jump if not zero) or sw (switch, case selection) instructions to change the control flow manually.

Functions

There's no function declaration. You just use a label to mark a spot in the code. You push all arguments on the stack in reverse order using pushi and pushf, then you use a call mnemonic with that label. Within the function, you can get the address of these parameters with the adr (address) instruction, with its parameter being the function parameter's number multiplied by four. For example adr 0 loads the first function parameter's address in the accumulator register, and adr 4 loads the second's. You can return from the function with the ret instruction. Return values are returned in the accumulator register, which you can set directly with the ci (constant integer) and cf (constant float) instructions, and indirectly with the popi, popf, ldb, ldw, ldi and ldf instructions. After the call it is the caller's responsibility to remove the parameters from the stack by using an sp + number of parameters times four instruction.

Provided Functions

You have all the MEG-4 API functions at your disposal; using the exact names as they are listed in this documentation.

You have to push all arguments on the stack in reverse order, then use an scall (system call) mnemonic with a MEG-4 API function name as parameter. After the call it is the caller's responsibility to remove the parameters from the stack.

Mnemonics

Before we go into the details, we must talk about the MEG-4 CPU specification.

The MEG-4 CPU is a 32-bit, little endian CPU. All values are stored in a way that smallest digits are placed on the smaller addresses. It is capable of performing operations on 8 bit, 16 bit and 32 bit integers (signed and unsigned) and on 32 bit floating point numbers.

The memory model is flat, meaning all data can be accessed through a single offset. Has no paging and no virtual address translation, no segmentation, except all data and code segment references are implicit (aka. no segment prefixes, referencing segments are automatic).

For security reasons code segment and data segment are separated, as well as the call stack and the data stack. Stack overflow and any other code injection through buffer overflow attacks are simply impossible on this CPU, which makes it very secure and bullet-proof (also supporting 3rd party bytecode like Lua would be impossible without code separation). In this reagard it is more like a Harvard architecture, but in every other aspect it's more like a von Neumann architecture.

The CPU has the following registers:

• AC: accumulator register, with an integer value
• AF: accumulator register, with a floating point value
• FLG: processor flags (setup is done, blocked for I/O, blocked for timer, execution stopped)
• TMR: the timer register's current value
• DP: data pointer, this points to the top of the used global variable memory
• BP: base pointer, marks the top of the function stack frame
• SP: stack pointer, the bottom of the stack
• CP: callstack pointer, the top of the callstack
• PC: program counter, the address of the instruction currently being executed

The data segment is byte based, meaning DP, BP and SP registers point to 8 bit units. You can place data to the data segment using the db (8 bit), dw (16 bit), di (32 bit) and df (32 bit float) mnemonics. These might have one or more comma separated arguments, and for db strings literals and character literals can also be used.

The code segment has a 32 bit granularity, meaning that's the smallest address unit you can use. For this reason the PC points to these 32 bit units and not bytes. The following mnemonics can be used to place instructions to the code segment:

The sw mnemonic has variable number (but at least three) arguments. The first one is a number, the second is a code label, as well as all the rest are code labels. It subtracts the number from the accumulator and checks if the result is positive and less than the number of the labels given. If not, then it jumps to the first label in the second argument. If it is, then it picks the accumulatorth label starting from the third parameter (second label), and jumps there.

So in a nutshell it is

sw (value), (label to jump to otherwise),
  (label to jump to if accumulator equals value),
  (label to jump to if accumulator equals value + 1),
  (label to jump to if accumulator equals value + 2),
  (label to jump to if accumulator equals value + 3),
  ...
  (label to jump to if accumulator equals value + N)

Every sw mnemonic might have up to 256 value labels.

Lua

If you want to use this language, then start your program with a #!lua line.

Example Program

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Further Info

Unlike the other languages, this isn't integral part of MEG-4, rather provided by a thrid party library. Due to that it does not (and cannot) have perfect integration (no debugger and no translated error messages for example). Its runner is bloated and much slower compared to the other languages, but it works, and you can use it.

The embedded version is Lua 5.4.6, with modifications. For security reasons it lacks concurrency, as well as module loading, file access, pipes, command execution. The coroutine, io and os modules and their functions aren't available (but the language features and all the other parts of the baselib are still there). Instead of these, it has the MEG-4 API, which can be used as in any other language, with some slight, minor differences for better integration.

If you're interested in this language then you can find more information in the Programming in Lua documentation.

API Differences

• memsave can accept either a MEG-4 memory address (integer) or a Lua table with integers (supposed to be a byte array).
• memload on call, a valid MEG-4 memory address must be passed, but then it returns a Lua table anyway. If you don't want to load to a specific MMIO area, then specify MEM_USER (0x30000) and just simply use the data in the returned Lua table.
• memcpy parameters can be two MEG-4 memory addresses as usual, or one of them can be a Lua table (just one, not both). You can use this function to copy data between MEG-4 memory and Lua (but inb and outb also works).
• remap only accepts a Lua table (with 256 integer values).
• maze instead of the last two parameters (numnpc and npc) one single Lua table (with each element being another table) can be used.
• printf, sprintf and trace does not use MEG-4's format string rules, but Lua's (however these two are almost entirely identical).

Memory Map

Misc

All values are little endian, so the smaller digit is stored on the smaller address.

The performance counter shows the time unspent when the last frame was generated. If this is zero or negative, then it means how much your loop() function has overstepped its available timeframe.

Pointer

The pointer buttons are as follows:

The upper bits of the pointer sprite index are used for hotspots: bit 13-15 hotspot Y, bit 10-12 hotspot X, bit 0-9 sprite. There are some predefined built-in cursors:

Keyboard

The keys popped from the queue are represented in UTF-8. Some invalid UTF-8 sequences represent special (non-printable) keys, for example:

The scancodes are as follows:

Gamepad

The gamepad buttons are as follows:

The △△▽▽◁▷◁▷ⒷⒶ sequence makes the KEY_CHEAT "key" pressed.

Graphics Processing Unit

Digital Signal Processor

The DSP status registers are all read-only, and for each channel they look like:

The first 4 channels are for the music, the rest for the sound effects.

Note that the waveform index 0 means "use the previous waveform", so index 0 cannot be used in the selector. The format of every other waveform:

The format of the sound effects and the music tracks are the same, the only difference is, music tracks have 4 notes per row, one for each channel, and there are 1024 rows; while for sound effects there's only one note and 64 rows.

The counting of notes goes as follows: 0 means no note set. Followed by 8 octaves, each with 12 notes, so 1 equals to C-0, 12 is B-0 (on the lowest octave), 13 is C-1 (one octave higher) and 14 is C#1 (C sharp, semitone higher). For example the D note on the 4th octave would be 1 + 4*12 + 2 = 51. The B-7 is 96, the highest note on the highest octave. You also have built-in defines, for example C-1 is NOTE_C_1 and C#1 is NOTE_Cs1, if you don't want to count then you can use these as well in your program.

For simplicity, MEG-4 uses the same codes as the Amiga MOD file (this way you'll see the same in the built-in editor as well as in a third party music tracker), but it does not support all of them. As said earlier, these codes are represented by three hex numbers, the first being the type t, and the last two the parameter, xy (or xx). The types E1 to ED are all stored in the type byte, although it looks like one of their nibble might belong to the parameter, but it's not.

User Memory

Memory addresses from 00000 to 2FFFF belong to the MMIO, everything above (starting from 30000 or MEM_USER) is freely usable user memory.

This is followed by the global variables that you have declared in your program, followed by the constants, like string literals. In case of BASIC, then this is followed by the actual DATA records.

Memory addresses above the initialized data can be dynamically allocated and freed in your program via the malloc and free calls.

Lastly the stack, which is at the top (starting from C0000 or MEM_LIMIT) and growing downwards. Your program's local variables (that you declared inside a function) go here. The size of the stack always changes depending on which function calls which other function in your program.

If by any chance the top of the dynamically allocated data and the bottom of the stack would overlap, then MEG-4 throws an "Out of memory" error.

Format String

Some functions, printf, sprintf and trace use a format string that may contain special characters to reference arguments and to describe how to display them. These are:

You can add padding by specifying the length between % and the code. If that starts with 0, then value will be padded with zeros, otherwise with spaces. For example %4d will pad the value to the right with spaces, and %04x with zeros. The f accepts a number after a dot, which tells the number of digits in the fractional part (up to 8), eg. %.6f.

3D Space

In MEG-4, the 3 dimensional space is handled according to the right-hand rule: +X is on the right, +Y is up, and +Z is towards the viewer.

  +Y
   |
   |__ +X
  /
+Z

Each point must be placed in the range -32767 to +32767. How this 3D world is projected to your 2D screen depends on how you configure the camera (see Graphics Processing Unit address 0049E). Of course, you have to place the camera in the world, with X, Y, Z coordinates. Then you have to tell where the camera is looking at, using pitch and yaw. Finally you also have to tell what kind of lens the camera has, by specifying the field of view angle. That latter normally should be between 30 (very narrow) and 180 degrees (like fish and birds). MEG-4 supports up to 127 degrees, but there's a trick. Positive FOV values will be projected as perspective (the farther the object is, the smaller it is), but negative values also handled, just with orthographic projection (no matter the distance, the object's size will be the same). Perspective is used in FPS games, while the orthographic projection is mostly preferred by strategy games.

You can display a set of triangles (a complete 3D model) using the mesh function efficiently. Because models probably have local coordinates, that would draw all models one on top of another around the origo. So if you want to dispay multiple models in the world, first you should translate them (place them) into world coordinates using trns, and then use the translated vertex cloud with mesh (moving and rotating the model around won't change the triangles, just their vertex coordinates).

Console

putc

1

printf

1

getc

1

gets

1

trace

1

delay

1

exit

1

Audio

sfx

1

music

1

GPIO

gpio_rev

1

gpio_get

1

gpio_set

1

Graphics

cls

1

cget

1

pget

1

pset

1

width

1

text

1

line

1

qbez

1
2

cbez

1
2

tri

1

ftri

1

tri2d

1
2
3

tri3d

1
2
3

tritx

1
2
3

mesh

1

rect

1

frect

1

circ

1

fcirc

1

ellip

1

fellip

1

move

1

left

1

right

1

up

1

down

1

color

1

forw

1

back

1

spr

1

dlg

1
2
3
4

stext

1

remap

1

mget

1

mset

1

map

1

maze

1
2

Input

getpad

1

prspad

1

relpad

1

getbtn

1

getclk

1

getkey

1

popkey

1

pendkey

1

lenkey

1

speckey

1

Mathematics

rand

1

rnd

1

float

1

int

1

floor

1

ceil

1

sgn

1