This repository contains everything required to produce a DOOM-like using PICO8, featuring:
- Complex geometry (slanted walls, stairs, doors...)
- Textured floors & walls (inc. transparent walls, animated triggers)
- Lightning (blinking sectors, light triggers)
- 8 sided sprites for monsters & props
- Triggers (opening/closing doors)
- Keys
- Multiple weapons (bullets & projectiles)
Level building and monster logic uses standard DOOM concepts & editors and is fully modable.
note: the toolkit is NOT a 100% complete DOOM port - many features are not supported (and never will be).
note: this documentation is using Slade3
note: the game does not require an official DOOM WAD
Original assets - Id Software (Bethesda)
ZDoom Wiki (outstanding content folks!)
- PICO8 to run game
- Python 3.6+ to pack levels into pico8 carts
- Slade 3 to edit levels
- ZBSP to produce UDMF files from levels
- Clone repo
- Open a Python command prompt at repo location
- (optional) Create a Python virtual env:
python -m venv env sandbox/script/activate
- Install WAD compiler:
pip install tools/wad_reader-0.1.tar.gz
- Validate install
Expected output:
python -m wad_reader
usage: wad_reader.py [-h] pico carts mod map positional arguments: pico full path to PICO8 folder carts path to carts folder where game is exported mod game cart name (ex: poom) map map name to compile (ex: E1M1) optional arguments: -h, --help show this help message and exit
-
Open a Python command prompt at repo location (e.g. where DECORATE file is)
-
(optional) Enable Python virtual env
-
Generate a PICO8 multi-cart game with a sample level in carts folder:
python -m wad_reader <path to PICO8> <path to carts folder> <mod name> <map name>
Example:
cd poom-sdk python -m wad_reader d:\pico-8_0.2.0 poom E1M1
-
Launch game:
pico8 -home <path to repo> poom.p8
The toolkit supports file-based DOOM archive only.
Archive structure:
- 📁 maps/ contains levels WAD files
- 📁 graphics/ contains image assets (inc. menu)
- 📄 PLAYPAL game palette ramp
- 📄 PAINPAL pain palette ramp
- 📄 DECORATE define actors & behaviors
- 📄 TEXTURES defines floor & wall textures
Open poom-sdk level folder:
Open the maps folder from Slade:
Create a new map (say E1M3) using UDMF format.
maps must be named ExMx
Set the base archive to POOM (to use main game resources)
From the map editor, select the "Draw Shape" option (defaults to rectangle), create a new room:
Select all four walls and assign "middle" texture:
Switch to sector mode and assign floor and ceiling textures:
Check level using 3d view:
Save level under: repo location/maps
Slade3 will display the settings window to get ZBSP compiler path. This is a good time to fill it with your own path:
Switch to "Things" mode to set player's starting location. Right click inside the room:
Edit thing type (should not be necessary as first thing created by Slade is player's location):
Select thing ID 1 (e.g. POOM guy!):
The following sector behaviors are supported:
ID | Type | Description |
---|---|---|
65 | Light Flicker | Random light flicker |
69 | 10 Damage | 10 HP every 15 ticks |
71 | 5 Damage | 5 HP every 15 ticks |
80 | 20 Damage | 20 HP every 15 ticks |
115 | Instadeath | Kills any actor touching sector floor |
The following triggers are supported:
ID | Type | Description |
---|---|---|
202 | Generic Door | Lower/raise sector ceiling. See: Generic Door |
64 | Platform Up/Down/Stay | Lower/raise sector floor. See: Platform Up/Down/Stay |
112 | Light Change | Set sector light. See: Light Change To Value |
All wall & floors textures (aka "flats") must be stored as single image. The tileset can be up to 1024x128 pixels.
The toolkit automatically converts tileset into unique 8x8 tiles.
The tileset cannot contain more than 128 unique tiles.
Example tileset:
Resulting PICO8 tiles:
Edit the tileset picture using your favorite paint program. Make sure to use only colors from the game palette, save file.
From Slade, launch the texture editor:
Create a new texture:
Specify texture name (to be used in editor) and size (in pixels):
Attach a patch (e.g. source image) to the texture:
make sure to use the full path option to locate the tileset
Move the texture area over the correct patch location:
Adjust texture scale to 0.5/0.5 to match in-game scale.
Save.
The texture is now available in level editor!
The game support 2 palettes:
- Game palette - used to shade textures & things
- Pain palette - used to fade to red screen when player gets hit
Must be a 16x16 image using only colors from row 0 of pain palette.
Default palette:
Must be a 16x16 image - can use any PICO8 colors (inc. secret colors).
Default palette:
Column 0 is the game palette.
Tip: use @Kometbomb Fade Generator to produce pain palette!
Game title is packaged from graphics/m_title.png image.
Image must be 128x32
Image must use standard PICO8 palette
The DECORATE file describes everything the player will find in the game (monsters, keys, medkits, props...). Each entry is an actor. An actor on the map is a thing (e.g. a thing always references an actor).
actor classname [ : parentclassname] [doomednum]
{
properties
flags
states
}
-
classname
The name this new actor is referenced by in the game. While ZDoom will accept a much larger range of values for the name, this should for best compatibility be a valid identifier (alphanumeric plus underscores, but not starting with a digit).
-
parentclassname
The name of a parent class this new actor inherits its attributes from (optional). If none is specified, the parent class is Actor.
-
doomednum
Editor number for this actor (optional). This is the number used to distinguish the actor from other things in map. If the actor is intended to be placed in a map editor, it should have an editor number. The actual number value is generally arbitrary but should avoid conflicting with already used numbers.
An actor definition consists of properties, flags and state definitions. In the state definitions you can call Action functions.
Actor properties and flags define the general behavior of an actor.
States define the various sprite animations of an actor.
Action functions (also known as "code pointers") cause the actor to perform some particular action when the frame that calls them is shown. They form the basis of almost all enemy and weapon behavior in the game. Instead of using one of the special action functions you can also use almost any action special that is available in ACS.
Comments are supported. Both types of C-style comments (// to end of line, and /* to */) are allowed. While not part of the specification, certain editing tools, such as Doom Builder and SLADE 3, make use of specific comments for special purposes, these usually start with //$.
The following actors are built-in parent class names:
actor key {
amount 1
maxamount 1
radius 20
}
actor ammo {
radius 20
}
actor health {
maxamount 200
radius 20
}
actor ammo {
maxamount 200
radius 20
}
actor weapon {
radius 20
amount 0
maxamount 1
}
actor player {
radius 32
armor 100
health 100
speed 3
+SHOOTABLE
+SOLID
}
actor monster {
radius 20
armor 0
health 50
+SHOOTABLE
+SOLID
}
actor projectile {
damage 1
speed 5
+NOGRAVITY
+MISSILE
}