gamespark

v1.1.0

Published

5 months ago

Game Spark development engine

0High
0Medium
0Low

GameSpark 🎮

A PICO-8 inspired game development engine that runs in the browser. Write games using familiar PICO-8 functions in JS or TS!

Features

PICO-8 Compatible API: Use familiar functions like cls(), pset(), print(), rectfill(), etc.
Web Component: Games run in a <game-spark> custom element
TypeScript Support: Full type definitions for all PICO-8 functions
Hot Reload: Instant updates during development
128x128 Resolution: Classic 128x128 resolution with pixel-perfect scaling
16-Color Palette: Authentic PICO-8 color scheme
Project Initialization: Quick setup with init command
Flexible Entry Points: Supports both JavaScript (.js) and TypeScript (.ts) files

Quick Start

Option 1: Initialize a New Project

# Create a new JavaScript project
npx gamespark init

# Or create a new TypeScript project
npx gamespark init --ts

# Or create a new project with git initialized
npx gamespark init --git

# Or create a new TypeScript project with git
npx gamespark init --ts --git

# Then start developing
npm start

Option 2: Manual Setup

npm install gamespark

Create Your First Game

Create a game file (e.g., src/main.ts or src/main.js):

// Clear screen with dark blue
cls(1);

// Draw a simple scene
print("Hello GameSpark!", 20, 60, 7);
rectfill(50, 50, 77, 77, 8);
circfill(64, 64, 10, 10);

Run the development server:

# With TypeScript
npx gamespark src/main.ts

# Or with JavaScript
npx gamespark src/main.js

Open http://localhost:3000 to see your game!

CLI Usage

npx gamespark [command] [options] [entry-file]

Commands

init - Initialize a new GameSpark project
update - Update GameSpark to the latest version

Options

--ts - Use TypeScript (only with init)
--git - Initialize git repository (only with init)
--help, -h - Show help message

Examples

# Start development server with TypeScript
npx gamespark src/main.ts

# Start development server with JavaScript
npx gamespark src/main.js

# Initialize new JavaScript project
npx gamespark init

# Initialize new TypeScript project  
npx gamespark init --ts

# Initialize new project with git
npx gamespark init --git

# Initialize new TypeScript project with git
npx gamespark init --ts --git

# Update GameSpark to latest version
npx gamespark update

# Show help
npx gamespark --help

Entry File Support

GameSpark supports both JavaScript and TypeScript entry files:

TypeScript files (.ts) - Full type checking and IntelliSense support
JavaScript files (.js) - Works out of the box, no configuration needed

When using init --ts, a TypeScript configuration is automatically created. TypeScript is included with GameSpark, so no additional dependencies are needed.

API Reference

Drawing Functions

cls(color?) - Clear screen
pset(x, y, color?) - Set pixel
pget(x, y) - Get pixel color
print(text, x?, y?, color?) - Print text
rect(x1, y1, x2, y2, color?) - Draw rectangle outline
rectfill(x1, y1, x2, y2, color?) - Draw filled rectangle
circ(x, y, r, color?) - Draw circle outline
circfill(x, y, r, color?) - Draw filled circle
line(x1, y1, x2, y2, color?) - Draw line

Math Functions

rnd(n?) - Random number
flr(x) - Floor
ceil(x) - Ceiling
abs(x) - Absolute value
sqrt(x) - Square root
sin(x), cos(x) - Trigonometry
atan2(y, x) - Arc tangent
min(a, b), max(a, b) - Min/max
mid(a, b, c) - Median
sgn(x) - Sign

Color Palette

0: Black    4: Brown     8: Red      12: Blue
1: Dark Blue 5: Dark Grey 9: Orange   13: Indigo  
2: Purple   6: Light Grey 10: Yellow  14: Pink
3: Green    7: White     11: Green   15: Peach

Using as a Web Component

You can also use GameSpark directly in HTML:

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="node_modules/gamespark/dist/GameSparkComponent.js"></script>
</head>
<body>
  <game-spark src="my-game.js"></game-spark>
</body>
</html>

Project Structure

When you use init, GameSpark creates this structure:

your-game/
├── package.json     # Project configuration
├── tsconfig.json    # TypeScript config (if --ts used)
├── .gitignore       # Git ignore file (includes dist/)
├── .git/            # Git repository (if --git used)
├── src/             # Source files
│   └── main.ts/.js  # Your game entry point
└── dist/            # Built files (created on first run)
    ├── main.js      # Compiled game
    └── index.html   # Development page

Development

The CLI automatically:

Bundles your game code (JavaScript or TypeScript)
Injects PICO-8 compatible function bindings
Starts a development server with hot reload
Serves the GameSpark web component

TypeScript Support

GameSpark includes full TypeScript definitions and the TypeScript compiler. Your editor will provide:

Autocomplete for all functions
Parameter hints and documentation
Type checking for coordinates and colors

TypeScript configuration is only created when using init --ts. For existing projects, you can use TypeScript files directly without any additional setup.

License

MIT