Skip to content
🐶 ultra-portable fantasy console
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
engines/js
games
libraries
tests
.gitignore
LICENSE.md
LOGO.png
README.md

README.md

pup is a minimalist ultra-portable fantasy console.

  • 64x64 pixel screen
  • 8x8 pixel 4 color sprites
  • 16 color palette
  • lua game code
  • 6 keys (incl. 4 directional)
  • 4 channel bleep-based audio
  • Built-in sprite editor ( Ctrl+1 )
  • Built-in audio editor ( Ctrl+2 )

High portability is achieved though offloading as much of console "hardware" engine code to lua. Since lua support should already be implemented in any engine (to run game code), the engines are maintained as small as possible. As such, implementing new engines will take minimal effort.

Usage (JS engine)

  • wget -P engines/js/ https://github.com/fengari-lua/fengari-web/releases/download/v0.1.4/fengari-web.js - download fengari-web.js into engines/js/
  • Launch a simple HTTP server in the root dir of pup: python -m SimpleHTTPServer or php -S localhost:8000 or anything similar
  • Go to http://localhost:8000/engine/js/index.html?game=_example in your browser of choice
  • Substitute _example in the link above to run other games

Registered Commands

  • pup(x, y) - put pixel
  • pul(x1, y1, x2, y2) - put line
  • pui(x1, y1, x2, y2, x3, y3) - put triangle
  • pue(x, y, w, h) - put ellipse
  • pur(x, y, w, h) - put rectangle
  • pus(i, x, y) - put sprite i from sprite sheet
  • put(str, x, y) - put text
  • pal(index) - select palette color index
  • sos(channel, note, gain) - sound a single beep (gain to zero to mute channel)
  • sop(from, to, loop) - sound playback from note sheet
  • som() - all sound mute, the way to stop looped sounds

Lua table manipulations

  • `tri(t, index) - table remove by index
  • `trc(t, condition) - table remove by condition

Lua aliases (recommended to use instead of calling lua functions directly):

  • sin(x) - math.sin
  • cos(x) - math.cos
  • ata(x, y) - math.atan
  • int(x) - math.floor
  • rnd() - math.random
  • str(n) - tostring
  • num(s) - tonumber

Registered Varibales

  • gn - Game Name
  • ga - Game Author
  • kl - LEFT key state
  • kr - RIGHT key state
  • ku - UP key state
  • kd - DOWN key state
  • ka - ACTION key A state
  • kb - ACTION key B state
  • dt - Delta Time since last "step"
  • tt - Total Time (dt accumulated over time)

Constant values:

  • sw - Screen Width in pixels (default 64)
  • sh - Screen Height in pixels (default 64)
  • pw - sPrite Width in pixels (default 8)
  • ph - sPrite Height in pixels (default 8)
  • ac - Audio Channels amount (default 4)
  • fw - Font Width (default 4)
  • fh - Font Height (default 4)
  • fs - Font Spacing, in pixels between characters (default 1)

Key states

  • kX = 0 - not pressed
  • kX = 1 - just pressed (fires only once per key press)
  • kX = 2 - pressed
  • kX =-1 - just released (fires only once when key was released)

Cart file structure

Game cartridges are stored in *.pup files. File always starts with .VER X version header. Following this are several possible sections:

  • .NAM - cart name (max 8 length)
  • .AUT - author name (max 10 length)
  • .SPR - sprite sheet
  • .SND - note sheet
  • .INI - initialization code, gets run only once when cart has been loaded
  • .STE - game step code, gets run repeatedly 60 times per second once the game has been initialized

TODO:

  • C / SDL engine (native win, mac, linux executables)
  • Sprite editor scrolling
  • Create new empty games
  • Code editor (is this needed really???)
  • Alias most used lua functions for convenience
You can’t perform that action at this time.