meg4/docs/en/formats.md

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.

HINT: One of the test tools, the converter can be used to convert floppies into zip archives. And the advcomp compiler can convert [adventure game] JSON files into playable zip project files.

Files in the project 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 perfectly 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, as for the note patterns only the first pattern used, and only one channel (64 notes in total, one for each sound effect).

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.

WARN: The Amiga MOD format is a lot more featureful than what the MEG-4 DSP chip can handle. Keep this in mind when you edit .mod files in third party trackers! Waveforms can't be longer than 16376 samples and songs longer than 16 patterns (1024 rows) will be truncated on import. Pattern order will be linearized, and although pattern break 0xD handled, other pattern commands are simply skipped. Also if you import multiple tracks, then they will share the same 31 samples.

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.

By default, MEG-4 supports the Raspberry Pi 3B+ GPIO pin layout, but you can load any arbitrary configuration from a plain text file. Here the first line must be "GPIO Layout", the second line is the name of the board, the third line is the device file, and the rest is a list of physical pin - GPIO register offset mappings (where -1 means the pin is not assigned to the GPIO chip, eg. voltage or ground pins). For an example, see src/misc/gpio.txt.

It is also possible to import AdvGame 2.0 [Adventure Game] archives, although point'n'click games will be reduced to textual games.

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.