Skip to content

freds72/poom-sdk

Repository files navigation

POOM SDK

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

Credits

Original assets - Id Software (Bethesda)

ZDoom Wiki (outstanding content folks!)

Getting Started

Pre-Requisites

  • 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

Install Toolchain

  1. Clone repo
  2. Open a Python command prompt at repo location
  3. (optional) Create a Python virtual env:
    python -m venv env
    sandbox/script/activate
  4. Install WAD compiler:
    pip install tools/wad_reader-0.1.tar.gz
  5. Validate install
    python -m wad_reader
    Expected output:
    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
    

Compile & Run Poom

  1. Open a Python command prompt at repo location (e.g. where DECORATE file is)

  2. (optional) Enable Python virtual env

  3. 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
    
  4. Launch game:

    pico8 -home <path to repo> poom.p8
    

Make a Game!

Level Building

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

My First Level

Open poom-sdk level folder:

Open Directory

Open the maps folder from Slade:

Open Maps

Create a new map (say E1M3) using UDMF format.

maps must be named ExMx

Map Type

Set the base archive to POOM (to use main game resources)

Base Archive

From the map editor, select the "Draw Shape" option (defaults to rectangle), create a new room:

Create Room

Select all four walls and assign "middle" texture:

Texture

Switch to sector mode and assign floor and ceiling textures:

Sector Textures

Check level using 3d view:

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:

ZBSP Settings

Switch to "Things" mode to set player's starting location. Right click inside the room:

Create Thing

Edit thing type (should not be necessary as first thing created by Slade is player's location):

Player Settings

Select thing ID 1 (e.g. POOM guy!):

Select POOMGuy

Sector Specials

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

Line Specials

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

Animated Triggers

Graphics

Flats

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:

Tileset

Resulting PICO8 tiles:

In Game Tiles

Creating New Texture

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:

Texture Editor

Create a new texture:

New Texture

Specify texture name (to be used in editor) and size (in pixels):

Texture Settings

Attach a patch (e.g. source image) to the texture:

make sure to use the full path option to locate the tileset

Patch Selection

Move the texture area over the correct patch location:

Patch

Adjust texture scale to 0.5/0.5 to match in-game scale.

Save.

The texture is now available in level editor!

Palettes

The game support 2 palettes:

  • Game palette - used to shade textures & things
  • Pain palette - used to fade to red screen when player gets hit

Game Palette

Must be a 16x16 image using only colors from row 0 of pain palette.

Default palette:

Game palette

Pain Palette

Must be a 16x16 image - can use any PICO8 colors (inc. secret colors).

Default palette:

Pain palette

Column 0 is the game palette.

Tip: use @Kometbomb Fade Generator to produce pain palette!

Game Title

Game title is packaged from graphics/m_title.png image.

Title Image

Image must be 128x32

Image must use standard PICO8 palette

Monsters & Props

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).

Syntax

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 //$.

Standard Classes

The following actors are built-in parent class names:

key

actor key {
    amount 1
    maxamount 1
    radius 20
  }

ammo

actor ammo {
    radius 20
  }

health

actor health {
    maxamount 200
    radius 20
  }

armor

actor ammo {
    maxamount 200
    radius 20
  }

weapon

actor weapon {
    radius 20
    amount 0
    maxamount 1
  }

player

actor player {
    radius 32
    armor 100
    health 100
    speed 3
    +SHOOTABLE
    +SOLID
  }

monster

actor monster {
    radius 20
    armor 0
    health 50
    +SHOOTABLE
    +SOLID
  }

projectile

actor projectile {
    damage 1
    speed 5
    +NOGRAVITY
    +MISSILE
  }