frogjs

v1.0.0-alpha.14

Published

a month ago

FrogJS - A simple framework for making games with symbols/emojis on a grid

Downloads

318

0High
0Medium
0Low

phaser-editor-2d

frogjs game emoji symbols grid canvas framework game-framework 2d-game browser-game

FrogJS

A minimal framework for making games with emojis and symbols on a grid.

Features

🎮 Grid-based rendering
🔢 Integer coordinates only (by design!)
🎯 No assets needed - emojis and characters only
🚀 Lightweight and fast
📦 TypeScript support included
🤖 AI-friendly with comprehensive guidelines

Installation

Via CDN (Recommended)

<script type="module">
  import { Game, Sprite } from 'https://cdn.jsdelivr.net/npm/frogjs/dist/frog.js';
</script>

Via npm

npm install frogjs

import { Game, Sprite } from 'frogjs';

Quick Start

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My FrogJS Game</title>
  <style>body { margin: 0; padding: 0; overflow: hidden; }</style>
</head>
<body>
  <script type="module">
    import { Game, Sprite } from 'https://cdn.jsdelivr.net/npm/frogjs/dist/frog.js';
    
    // Create game
    const game = new Game({
      gridWidth: 20,
      gridHeight: 36,
      theme: 'classic',
      orientation: 'portrait',
      name: 'My Game'
    });
    
    // Create player
    const player = new Sprite({ symbol: '🐸', x: 10, y: 7 });
    game.addSprite(player);
    
    // Game loop with movement
    game.onUpdate = () => {
      if (game.isLeftKeyDown() && player.x > 0) player.x--;
      if (game.isRightKeyDown() && player.x < 19) player.x++;
      if (game.isUpKeyDown() && player.y > 0) player.y--;
      if (game.isDownKeyDown() && player.y < 35) player.y--;
    };
  </script>
</body>
</html>

⚠️ Important: Integer Coordinates Only

FrogJS uses grid-based positioning with INTEGER coordinates only.

✅ CORRECT
sprite.x = 5;
sprite.y = 10;
player.x += 1;

❌ WRONG
sprite.x = 5.5;    // No fractional coordinates!
player.x += 0.1;   // No smooth movement!

See AI_GUIDELINES.md for complete details.

API Overview

Game

const game = new Game({
  gridWidth: 20,      // Grid width in cells
  gridHeight: 36,     // Grid height in cells
  theme: 'classic',   // Color theme: 'classic', 'midnight', 'forest', 'ocean', 
                      // 'sunset', 'neon', 'retro', 'mono', 'cyberpunk', 'pastel'
  orientation: 'portrait', // 'portrait' (GameBoy) or 'landscape' (Switch)
  name: 'My Game'     // Game name shown on device (default: 'FrogJS')
});

Device Orientation

All FrogJS games are wrapped in a retro console interface with on-screen controls. Choose the orientation:

// Portrait mode - looks like a GameBoy (vertical)
const game = new Game({
  orientation: 'portrait'
});

// Landscape mode - looks like a Nintendo Switch (horizontal)
const game = new Game({
  orientation: 'landscape'
});

Sprite

const sprite = new Sprite({
  symbol: '🐸',      // Emoji or character
  x: 10,             // Grid x (INTEGER!)
  y: 7,              // Grid y (INTEGER!)
  alpha: 1.0,        // Transparency
  z: 0,              // Render order
  angle: 0,          // Rotation (degrees)
  fixed: false,      // Ignore camera scroll
  color: '#ffffff'   // Symbol color
});

Methods

game.addSprite(sprite)
game.removeSprite(sprite)
game.getSprite(x, y)
game.getAllSprites(x, y)
game.clearSprites()
game.reset()  // Clear all state (sprites, animations, timers, callbacks, camera)

// Input - Polling (check if key is currently pressed)
game.isLeftKeyDown()
game.isRightKeyDown()
game.isUpKeyDown()
game.isDownKeyDown()
game.isSpaceKeyDown()

// Input - Event-based (register callbacks for key events)
game.onLeftKeyDown(callback, once?)   // Triggered when key is pressed
game.onLeftKeyUp(callback, once?)     // Triggered when key is released
game.offLeftKeyDown(callback)         // Remove a registered callback
game.offLeftKeyUp(callback)

// Same pattern for all keys:
// onRightKeyDown/Up, offRightKeyDown/Up
// onUpKeyDown/Up, offUpKeyDown/Up
// onDownKeyDown/Up, offDownKeyDown/Up
// onSpaceKeyDown/Up, offSpaceKeyDown/Up
//
// Use `once: true` for one-time callbacks:
// game.onSpaceKeyDown(() => jump(), true)  // Only fires once

// Animations
game.fadeSprite(sprite, startAlpha, endAlpha, duration, callback)
game.rotateSprite(sprite, startAngle, endAngle, duration, callback)

// Sound (Pascal-style)
game.sound(frequency, duration)  // frequency in Hz, duration in ms
// Example: game.sound(440, 200) plays A4 for 200ms

// Timing
game.timeout(delay, callback)
game.timer(delay, callback, times)

// Camera
game.scrollX = 0
game.scrollY = 0

Resources

TypeScript Definitions: dist/frog.d.ts
AI Guidelines: AI_GUIDELINES.md
Quick Reference: llm.txt
Examples: examples/

For AI Agents

If you're an AI agent generating FrogJS games:

Read this FIRST: AI_GUIDELINES.md
Quick ref: llm.txt
TypeScript defs: dist/frog.d.ts

Key constraint: INTEGER COORDINATES ONLY

Examples

See the examples/ directory for complete game examples.

License

MIT

Author

Arian Fornaris