Overview
PokeLoom is an engine and a creation kit for fan-made monster-collecting games. It is written from scratch in Rust. A game made with it looks and plays like the handheld games of the DS era: a 3D world built from a grid of pieces, flat sprite characters, two screens, touch menus on the lower one, and modern battle rules.
A PokeLoom game is a project folder of ordinary files:
- maps drawn in Tiled, a free map editor;
- models saved as OBJ and pictures saved as PNG;
- text files: settings in TOML, event scripts, dialogue, creature data.
The ploom command turns the folder into the game’s data, one file called
game.pak. The engine loads that file on every platform. The same folder builds
two ways:
| Build | Runs on |
|---|---|
| A desktop game | Windows, Linux and macOS, in one window that shows both screens |
A .nds ROM |
DS emulators; melonDS is the reference |
Both builds come from one engine and one set of rules. The same inputs and the same seed give the same game, frame for frame, on every platform. The DS build fits in the console’s 4 MB of RAM. Desktop and DS says what that promise covers.
Why a folder of plain files: a creator can read, diff and edit every part of a game with ordinary tools, keep it in version control, and see a change in the running game the moment the file is saved (live reload). Nothing is hidden in a binary format that only one editor can open.
Audience
Section titled “Audience”- Creators who want to make a game without writing Rust: maps in Tiled, scripts
in a small language, settings in
game.toml. - Creators who start from a game they own. The importer turns a ROM or a decompilation into an editable project; from there a game can be changed, remixed or restyled. See Import a game you own.
- Contributors who change the engine itself, in Rust, under its budgets and rules. See Engine internals.
Styles
Section titled “Styles”PokeLoom draws the field two ways. Both run on desktop and on DS.
- The DS look. A 3D world of pieces on a grid of cells, flat sprite characters, camera presets and camera zones, light that follows the hour, edge marking and weather, in the manner of Platinum, HeartGold and Black.
- The GBA look. A top-down world of 8×8 tiles in 16×16 metatiles on layers, in the manner of Emerald, drawn by the DS’s own 2D hardware. See The tile-map (GBA) style.
Planned (plan 35): Game Boy-era worlds as a mode of the tile-map renderer.
Art is grouped by role (grass, water, a house door, a ledge), and a game draws those roles with an art set. Changing the set restyles the game: a GBA-style world can be drawn with 3D pieces. See Asset roles and style chains.
Features
Section titled “Features”The aim is that every feature of every mainline game before the 3DS exists in the engine as a general feature, which any game can switch on. The engine never asks which game it is running; a difference between two games is a setting, a feature or content. One model, many games explains the rule.
Many of these features exist today: a joined world streamed as you walk, map variants, warp kinds, weather, a following creature, field moves, fishing, roamers, doubles, multi and tag battles, Mega Evolution and Terastallization, the party, bag, summary, storage, dex, trainer card and journal, the day care and eggs, the Hall of Fame, a challenge mode with permadeath, and a sectioned save. Others are designed and not built: seasons, moving map parts, contests, battle facilities, a device on the lower screen whose apps are registered by script, the minigame host. What is built today has the whole list.
Battle rules
Section titled “Battle rules”Every built-in battle mechanic is ported from Pokémon Showdown and checked by playing the same battle, with the same random numbers, in both. The event logs must match line for line. See Battle rules checked against Showdown.
Creature, move, ability and item data comes from Showdown’s published data, fetched
on the creator’s machine by ploom fetch-data. Pokémon Essentials PBS files are a
second source. Every game shares this one modern data set.
A game may add or override mechanics of its own, through data, script hooks or Rust in the game’s own crate. Those are declared, listed by the build and tested by the game’s own scenarios. See Your own battle mechanics.
Comparison
Section titled “Comparison”With Pokémon Essentials. Essentials is a kit for RPG Maker XP. PokeLoom fills the same role, with three differences: its games run natively on desktop and DS, they look like the handheld games rather than a PC RPG, and the engine is small and fast enough to stay inside the DS’s limits. The aim is Essentials’ power in a runtime that fits a DS. Porting an Essentials game is done by hand, or by an AI agent working from PokeLoom’s generated references, not by an automatic converter (decision 229).
With ROM hacking. A ROM hack patches a finished game and inherits its ceilings: a
fixed number of maps and zones, interface left over from the base game, data with no
use, and a patch file to apply. A PokeLoom game is built from a folder. Maps are
folders with no fixed count (up to 4,096), each game has its own interface, and
ploom check refuses broken files and measures every map against the DS’s budget
before the game ships. An import is a one-way conversion into such a folder: the
importer never writes a ROM or a patch.
Limits
Section titled “Limits”- It ships no Nintendo assets. The repository holds no art, audio, maps, text, stat tables or learnsets from any game, in its code, tests or history. Imported games, fetched data and fetched sprites are written only to folders git ignores, on the creator’s machine, and stay private.
- It is not a remake of any game. The sample game in
sample/is original, with its own creatures, places and story. - It is not a ROM editor. Imports convert a game into a project; nothing is written back into a ROM.
- It is not a GBA or 3DS engine. GBA-style games run on DS and desktop, using the DS’s hardware (decision 273). The 3DS generations come later, after every game before them (plan 35).
Next steps
Section titled “Next steps”- Install and Your first project.
- A tour of the sample game.
- How the DS works, for what the hardware asks of a game.