hazo_arcade

Reusable PixiJS 8 game engine library providing scene management, game loop, input, audio, config, collision, parallax, animation, effects, storage, UI tools, and Vite plugins — plus (since v3.0.0) a server-side gamification platform: currencies, wallets, transactions, collectibles, shop, engagement state, and bots.

Install

npm install hazo_arcade hazo_core pixi.js

hazo_core is a required peer dep (provides the workspace-standard HazoError subclasses, correlation IDs, config loader, and logger factory used by the engine). hazo_ui is an optional peer dep used only by the React UI modules.

Modules

Each module has its own subpath export — import only what you need:

import { initApp, SceneManager, GameLoop } from "hazo_arcade/core"
import { AudioManager } from "hazo_arcade/audio"
import { KeyboardInput } from "hazo_arcade/input"
import { parseIni, loadIni } from "hazo_arcade/config"
import { ConsoleLogger } from "hazo_arcade/logging"
import { circlesOverlap, rectCircleOverlap } from "hazo_arcade/collision"
import { ParallaxBackground } from "hazo_arcade/parallax"
import { SpriteAnimator } from "hazo_arcade/animation"
import { ScreenFlashEffect, createShadow } from "hazo_arcade/effects"
import { LeaderboardStore, CurrencyStore } from "hazo_arcade/storage"
import { loadJson } from "hazo_arcade/utils"

Or import everything from the barrel:

import { initApp, AudioManager, KeyboardInput, ... } from "hazo_arcade"

Engine Modules

| Module | Description | |--------|-------------| | core | App singleton, scene manager (stack-based push/pop/replace), fixed-timestep game loop, event bus, object pool | | audio | AudioManager wrapping @pixi/sound with mute persistence, SFX registration, music phases | | input | Generic keyboard input with action-to-keycode bindings | | config | INI parser with typed helpers, async fetch+cache loader | | logging | Console logger with levels and per-category overrides | | collision | Circle-circle and rect-circle overlap detection | | parallax | Multi-layer vertical scrolling background | | animation | Frame-by-frame sprite animation with states and play modes | | effects | Screen flash, expanding ring, drop-shadow utilities | | storage | LocalStorage/sessionStorage backed leaderboard and currency stores | | utils | Async JSON loader with caching |

UI Modules (React)

React-based development tools for sprite and audio management. These require React 18+ and related peer dependencies.

import { HazoSpriteManager } from "hazo_arcade/ui/sprite-manager"
import { HazoSoundManager } from "hazo_arcade/ui/sound-manager"
import { HazoUiSoundPlayer } from "hazo_arcade/ui/sound-player"
import { FrameExtractor } from "hazo_arcade/ui/frame-extractor"
import { EditableFilename, BulkOperationToolbar } from "hazo_arcade/ui/shared"
import { useAudioLibrary, useSoundAssignments, useMusicAssignments } from "hazo_arcade/ui/hooks"
import { formatTimeMs, parseTimeMs, cn } from "hazo_arcade/ui/utils"

Vite Plugins

Build-time plugins for sprite sheet and audio asset processing:

import { spriteEditorPlugin, audioPlugin } from "hazo_arcade/vite"

Server-side gamification (hazo_arcade/server)

Requires hazo_connect ^4.3.3 (required peer). Apply migrations/0001_arcade_server_economy.sql (SQLite, or via runMigrations()) / db_setup_postgres.sql (Postgres) before use.

import { createCurrencyService, createWalletService, createTransactionService } from "hazo_arcade/server"

const currencies = createCurrencyService(db)
const coins = await currencies.define({ code: "coins", name: "Coins" })

const wallets = createWalletService(db)
await wallets.credit(childId, coins.id, 10, { source: "session", referenceId: sessionId })
await wallets.debit(childId, coins.id, 4, { source: "shop_purchase", referenceId: itemId })

| Service | Table | Notes | |---------|-------|-------| | createCurrencyService | hazo_arcade_currencies | earnable/spendable/wagerable/purchasable flags | | createWalletService | hazo_arcade_wallets | atomic credit/debit via claimRows(), never negative | | createTransactionService | hazo_arcade_transactions | immutable ledger — no update/delete | | createCollectibleService | hazo_arcade_collectibles | skill binding + evolution-stage ladder | | createCollectionStateService | hazo_arcade_collection_state | per-user stage; advanceStage() never regresses | | createShopCatalogService | hazo_arcade_shop_catalog | item definitions | | createShopRotationService | hazo_arcade_shop_rotation | weekly rotation, injectable RNG for tests | | createShopInventoryService | hazo_arcade_shop_inventory | per-user purchases + refund marking | | createEngagementStateService | hazo_arcade_engagement_state | session streak (UTC day-based) | | createGameConfigService | hazo_arcade_game_config | key-value tunables | | createBotService | hazo_arcade_bots | bot profiles for the social/visit surface |

Peer Dependencies

Required:

• hazo_core ^1.0.0 — error classes, correlation IDs, config loader, logger
• hazo_connect ^4.3.3 — server-side CRUD + atomic claims (only if importing hazo_arcade/server)
• pixi.js ^8.0.0

Optional (engine):

• @pixi/sound ^6.0.0 — for audio module
• hazo_ui ^3.1.3 — for cn() and the React UI modules

Optional (UI tools):

• react ^18.0.0 || ^19.0.0, react-dom ^18.0.0 || ^19.0.0
• radix-ui ^1.0.0, lucide-react ^0.553.0
• class-variance-authority ^0.7.0, clsx ^2.1.1, tailwind-merge ^3.5.0
• rc-slider ^11.0.0
• @imgly/background-removal ^1.5.0
• jszip ^3.10.0

Optional (build tools):

• vite ^5.0.0

Tailwind CSS v4

If your project uses Tailwind CSS v4, add a @source directive so Tailwind scans the package's classes:

@import "tailwindcss";
@source "../node_modules/hazo_arcade/dist";

Requirements

• Node.js >= 18
• ESM only ("type": "module")

License

MIT