Project Lunar – Advanced Documentation

Developed and maintained by ModMyClassic (https://modmyclassic.com)

—

How the performance settings (extra clock speed, ZRAM Compression and external DRAM swap) works

– The higher clock speed is enabled via the options menu. By default the clock speed is stock at 1.00ghz and can be turned upto 1.344ghz. (Use at your own risk)
– ZRAM compression (DRAM optimisation) is enabled by default and toggable by option menu. It’s recommended you leave this on as it optimises the DRAM and usually prevents crashes in high memory use cases.
– External DRAM swap. If you use external memory, DRAM swap is enabled by default. The SWAP is engaged 10 seconds after powering on the console and creates a 256mb swap file on your external drive. This effectively creates a 256mb RAM sponge which soaks up any memory leakage to ensure that what little DRAM available is usable and not wasted on memory leaks or other static elements. Leaving this enabled is also recommended.

How External storage works

– `rootfs_data` is overlaid on top of the stock UI/emulator and RetroArch components almost immediately on boot.
– If external media is detected at any point, `rootfs_data` is overlay is unmounted and `media` is overmounted in it’s place. It will also overlay `/media/mega_drive_saves` onto `rootfs_data` for savestates. (Please refer below for more details about save states)

How saves and external storage work with Project Lunar

– If external media is inserted to the Mega Drive mini, it is automatically mounted and overlaid on top of the NAND. (See below for more details on overlay)
– After the media is overlaid, it will check all `data_X.bin` and `meta_X.bin` on the NAND to see if they exist on the external media under `/media/mega_drive_saves`
– Any `data_X.bin` and `meta_X.bin` that exist on NAND but not on the external media will be copied to the external media.
– If there is a copy of a savestate using the same filename on the NAND and the external media. The external media version will take presidense. **This means that only the savestate on the external media will be updated. The one of the NAND will be left untouched!**
– If external media with a newer version of the savestate is removed. The original savestate will still exist on the NAND.
– If the savestate is deleted from the external media but not from NAND, the old version of the savestate will be synced back to the external media on next boot.

**We intend on adding a savestate backup facility, ability to sync save states, and the ability to transfer save states to external media and wipe from NAND.**

Running a Project Lunar function from the commandline

There is a binary included called `project_lunar`, just run the command `project_lunar ` and it will run the appropriate function and pass the arguments as required

Partitions and how directories are overlaid onto the NAND partitions (Advanced)

Partitions/File Systems

– NANDA, NANDB, NANDC – Boot and Kernel
– NANDD – `rootfs` (Majority of OS and stock emulator sit here)
– NANDE – `rootfs_data` 170.4mb (Used for savestates, roms and cores)
– NANDF – `misc` (Used for flags by the stock emu, UI)
– NANDG – `project_lunar` (Previously unused, used for Project Lunar)

Special mounts

– `/dev/nandg` – `/opt/project_lunar` (Main mount location)
– `/dev/sda1` – `/media` (First available USB partition found)

Overlayfs mounts

– `/opt/project_lunar/bin` > `/bin` (overlayfs-bin)
– `/opt/project_lunar/etc` > `/etc` (overlayfs-etc)
– `/opt/project_lunar/var` > `/var` (overlayfs-etc)
– `/opt/project_lunar/usr/libexec` > `/usr/libexec` (overlayfs-etc)
– `/opt/project_lunar/lib` > `/lib` (overlayfs-lib)

Overlayfs mounts (NAND only)
– `/rootfs_data/retroarch` > `/opt/project_lunar/opt/retroarch/config/retroarch/config`
– `/rootfs_data/m2engage/system` > `/usr/game/system`
– `/rootfs_data/m2engage/region` > `/usr/game/${REGION}`

Overlayfs mounts (External Media)
– `/media/project_lunar/retroarch` > `/opt/project_lunar/opt/retroarch/config/retroarch/config`
– `/media/project_lunar/m2engage/system` > `/usr/game/system`
– `/media/project_lunar/m2engage/region` > `/usr/game/${REGION}`
– `/media/mega_drive_saves` > `/rootfs_data`

External Media directories

– `/media/mega_drive_saves`
– `/media/project_lunar`
– `/media/project_lunar/roms`
– `/media/project_lunar/m2engage/system/sound`
– `/media/project_lunar/m2engage/system/script`
– `/media/project_lunar/m2engage/system/roms`
– `/media/project_lunar/m2engage/system/motion`
– `/media/project_lunar/m2engage/system/font`
– `/media/project_lunar/m2engage/system/config`
– `/media/project_lunar/m2engage/region/script`
– `/media/project_lunar/m2engage/region/motion`
– `/media/project_lunar/m2engage/region/config`
– `/media/project_lunar/retroarch/assets`
– `/media/project_lunar/retroarch/autoconfig`
– `/media/project_lunar/retroarch/cheats`
– `/media/project_lunar/retroarch/cores`
– `/media/project_lunar/retroarch/database`
– `/media/project_lunar/retroarch/overlay`
– `/media/project_lunar/retroarch/playlists`
– `/media/project_lunar/retroarch/shaders`
– `/media/project_lunar/retroarch/system`
– `/media/project_lunar/retroarch/thumbnails`
– `/media/project_lunar/emustation`

Boot Priority (Advanced)

There are currently 35 extra init.d service scripts added to the boot order

– `S02_PL_init_nand` (initialising of disk and filesystems)
– `S03_PL_media_watch` (initialising of external media watchdog)
– `S97_PL_50_initiate_mod` (general Project Lunar init functions)
– `S97_PL_70_dbus` (initialising of DBUS (used for bluetooth))
– `S97_PL_90_networking` (initialising of network services)

If you require to add any further init.d service scripts, please add them before or after
`S97_PL_50_initiate_mod` by setting the integer prefix `S97_PL_XX` accordingly. i.e. `S97_PL_30_XXX` will start/stop before and `S97_PL_70_XXX` will start/stop after.

The stock initialising of `moon-game` (stock emulator) is intercepted by overlaying `S99first_startup`. This ensures all preliminary steps are carried out and launches directly to `boot_menu`. Depending if there is a `auto_boot` flag or not, it will either render the boot menu or automatically boot to whatever configured boot item. (RA, Stock UI, ES etc)

How updates and the new mod system work (Advanced)

There are three methods of updating a console running the project lunar payload. These are: (In execution order)

– Execute (binaries or `.sh` files)
– Transfer (any file or folder)
– Packages (`.mod` format packages)

These update routines can be interacted with from `/rootfs_data/project_lunar/update/` for NAND only and `/media/project_lunar/update/` for EXTERNAL MEDIA solutions.

You need to upload the files/diretories/packages required to the corresponding routine directory to either `/media` or `/rootfs_data`

i.e.

– `/rootfs_data/project_lunar/update/execute_update.sh`
– `/rootfs_data/project_lunar/update/transfer/opt/project_lunar/etc/project_lunar/test.txt`
– `/rootfs_data/project_lunar/update/transfer/rootfs_data/project_lunar/retroarch/cores/test-core.so`
– `/media/project_lunar/update/packages/test-mod_1.0.1_SEGAMD.mod`

When an update routine is triggered (NAND or MEDIA) a session log is saved to NAND (even if RO) to `/opt/project_lunar/log/last_update.log`. Files and directories used during the update routine will automatically clear themselves after execution regardless of success.

If you wish to create a mod for Project Lunar, you should always use the PACKAGE routine. The EXECUTE and the TRANSFER routines should only really be used by Project Lunar devs or on your own console for testing. If you submit a mod and it doesn’t use the PACKAGE routine it will likely be rejected unless there is good reason not to.

Mods should always be within PACKAGE format as there is an onboard package manager which keeps track of what mods are installed, what versions, by who etc etc. These mods can also be uninstalled cleanly by running `mod-remove`

Any mod package that is USB only must require `Type: USB_MOD` within the mod description.

When an update or package install is taking place, there wil be a live display on the screen printing what the console is currently doing and the console’s LED will flash repeatedly.

It should also be noted that all three routines will run in order: EXECUTE, TRANSFER and PACKAGE. There is no need to shutdown or restart the console as when the routines are finished (if triggered) it will trigger a 5 second delay and restart.

How to create your own .mod (Advanced)

Coming soon, if you have questions or require a makefile example just ask in the discord.

What CLI tools are there to interact with mod packages?

There are currently the following CLI tools which can be ran from the command prompt:

– `mod-info ` = Display information on the mod like title, version, author, dependencies etc
– `mod-install ` = Install mod
– `mod-list` = List currently installed mods and the versions installed
– `mod-remove` = Remove mod
– `mod-unpack` = Unpack mod contents butdon’t install

Online .mod support, desktop mod support and cross console support.

It is intended that you can manage your mods from the new Project Lunar desktop app and for network enabled consoles we also intend for users to be able to delete,install and update mods and updates from the console interface without the requirement of hooking up to a pc. As these features are implemented we will put it in the update notes.

Lastly we also plan to carry over the same `.mod` support for other consoles running any ModMyClassic software.

Automated Dev-Ops with Gitlab CI / CD

This Project is powered by GitLab’s CI/CD automated dev ops. This means this project will automatically build, test and deploy.

This whole process is handled by GitLab’s remote runners hosted within kubernetes clusters.