SpriteForge

A dual-layer 2D creative coding & game development platform powered by C# and Lua.

SpriteCore — Processing-like creative framework
SpriteEngine — p5engine-like 2D game engine
For Sprite, who makes every frame worth rendering.

---

✨ Features

• 🎨 Processing-Style API — Draw graphics with familiar setup() / draw() / update(dt) callbacks
• 🎮 Full Game Engine — GameObject/Component/Scene, Physics, Audio, Tween, UI, and more
• 📝 Lua Scripting — Drive your entire game from Lua scripts via NLua 5.4
• 📦 Asset Pipeline — Custom .spak resource pack format with compression and VFS mounting
• 🔧 Build System — SpriteBuild CLI (sbuild) for automated asset scanning, packing, and branded EXE generation
• 🤖 Hot Reload — Modify Lua scripts and see changes instantly without restarting
• 📱 Cross-Platform — Windows desktop + Android mobile (same Lua script runs on both)

---

🚀 Quick Start

Prerequisites

Platform	Requirements
Windows	.NET 10 SDK
Android	.NET 10 SDK + Android Workload, JDK 11+, Android SDK (API 36.1)

Clone & Build

git clone https://github.com/ShenyfZero9211/SpriteForge.git
cd SpriteForge

# Windows — build everything
dotnet build

# Android — Release build (required for Android 15 emulator)
dotnet publish SpriteLauncher.Android/SpriteLauncher.Android.csproj \
  -c Release -f net10.0-android36.1 \
  -p:JavaSdkDirectory="D:\Android\Android Studio\jbr" \
  -p:AndroidSdkDirectory="C:\Users\<User>\AppData\Local\Android\Sdk" \
  --no-restore

Run a Sample

# Windows — run the default Lua sample
dotnet run --project SpriteLauncher

# Windows — run a specific sample
dotnet run --project SpriteLauncher -- SpriteLauncher/lua-samples/05_GameObject/main.lua

# Android — install and launch
adb uninstall com.companyname.SpriteLauncher.Android
adb install -r SpriteLauncher.Android/bin/Release/net10.0-android36.1/com.companyname.SpriteLauncher.Android-Signed.apk
adb shell am start -n com.companyname.SpriteLauncher.Android/crc64be2250ed3f99cda3.MainActivity

---

📁 Project Structure

SpriteForge/
├── SpriteCore/                    # Creative coding framework (ClassLib)
│   ├── src/Graphics/              # SP5 / SPGraphics / SkiaGraphics
│   ├── src/Window/                # GameWindow + InputSystem (SDL2)
│   ├── src/Scripting/             # ScriptEngine (NLua)
│   ├── src/Time/                  # GameTimer
│   └── src/Utils/                 # Log system
│
├── SpriteEngine/                  # 2D game engine (ClassLib)
│   ├── src/Core/                  # EventSystem, Scheduler, ObjectPool, SPEngine
│   ├── src/Scene/                 # GameObject, Component, Transform, SceneManager
│   ├── src/Physics/               # RigidBody2D, Collider, PhysicsWorld2D
│   ├── src/Tween/                 # 31 easing functions, Sequence, TweenManager
│   ├── src/UI/                    # UIElement, UIManager, Widgets
│   └── src/LuaAPI/                # GameLuaAPI, TweenLuaAPI
│
├── SpriteLauncher/                # Windows console launcher
├── SpriteLauncher.Android/        # Android main activity (.NET Android)
├── SpriteBuild/                   # Build system (sbuild CLI)
│   ├── SpriteBuild.CLI/           # Command-line entry
│   ├── SpriteBuild.Core/          # Pipeline / Stage / BuildContext
│   ├── SpriteBuild.Analyzer/      # C# / Lua asset scanner
│   ├── SpriteBuild.Packager/      # .spak packer + texture preprocessor
│   └── SpriteBuild.Tests/         # Unit & integration tests
│
├── SpriteGuard/                   # Sample game (tower-defense / shooter)
├── SampleBrowser/                 # WinForms sample browser
└── docs/                          # Technical documentation

---

🛠️ Build System (sbuild)

SpriteBuild automates the entire "source to distributable" pipeline:

# Initialize sbuild.json
dotnet run --project SpriteBuild/SpriteBuild.CLI -- init MyGame

# Validate configuration and assets
dotnet run --project SpriteBuild/SpriteBuild.CLI -- validate

# Full build (compile → pack → assemble)
dotnet run --project SpriteBuild/SpriteBuild.CLI -- build

# Single-file release
sbuild build --single-file

Output (dist/):

• Branded *.exe entry point
• .spak resource packs (textures / audio / fonts)
• Native libraries (SDL2.dll, libSkiaSharp.dll, openal32.dll)

---

🧪 Tests

# Run all tests
dotnet test --no-restore -v q

# Specific modules
dotnet test SpriteCore.Tests
dotnet test SpriteEngine.Tests
dotnet test SpriteBuild/SpriteBuild.Tests

Current coverage: 561 tests (SpriteCore 93 + SpriteEngine 444 + SpriteBuild 24) — all passing.

---

📚 Documentation

Document	Path	Description
Agent Guide	AGENTS.md	Development conventions, traps, and cheat sheets
Dev Plan	DEVELOPMENT_PLAN.md	Full phase plan with milestones
Lua API Report	docs/LuaAPI-Extension-Report.md	Lua binding technical details
Core Architecture	docs/SpriteEngine-Core-Architecture.md	Core layer design decisions
Technical Report	docs/SpriteForge_Technical_Report.md	Phase 1 development report
Spak System	docs/SpriteForge_Spak_Resource_Pack_System.md	Asset pack format & VFS
Build Report	docs/SpriteBuild_Technical_Report.md	Build system architecture

---

🖼️ Samples

Sample	Path	Description
HelloSprite	lua-samples/01_HelloSprite/	Basic drawing API + mouse interaction
Shapes	lua-samples/02_Shapes/	All shapes + transforms + noise
ImageDemo	lua-samples/03_ImageDemo/	Image loading and tinting
TweenDemo	lua-samples/04_TweenDemo/	Tween animations & easing
GameObject	lua-samples/05_GameObject/	First game-level sample (GO + physics)
SpakDemo	lua-samples/06_SpakDemo/	Resource pack loading

Android Touch Demo (SpriteLauncher.Android/Assets/main.lua):

• Finger-following square with auto-rotation
• Target position indicator
• Interactive UI buttons (Color, Reset, Hide UI)
• Click particle effects

---

🏗️ Architecture

Lua Script Layer
       │
       ▼
┌─────────────────────────────────────────┐
│  SpriteCore (C# ClassLibrary)           │
│  ├── Graphics: SP5 → SPGraphics → Skia  │
│  ├── Window:   SDL2 + InputSystem       │
│  ├── Scripting: NLua 5.4 runtime        │
│  └── Time:     GameTimer (Stopwatch)    │
└─────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  SpriteEngine (C# ClassLibrary)         │
│  ├── Scene: GameObject / Component      │
│  ├── Physics: Aether.Physics2D          │
│  ├── Tween: 31 easing + Sequence        │
│  ├── UI: UIManager + Widgets            │
│  └── LuaAPI: GameLuaAPI / TweenLuaAPI   │
└─────────────────────────────────────────┘
       │
       ▼
  SpriteLauncher / SpriteLauncher.Android

---

⚠️ Known Issues

Issue	Platform	Workaround
Debug build crashes on Android 15 emulator	Android	Always use Release mode for Android 15
Splash Screen covers top UI (Android 12+)	Android	Call ReportFullyDrawn() or place UI below y=160
Assets cache not refreshed after update	Android	Uninstall + reinstall APK
rectMode state leaks after popMatrix	All	Explicitly reset rectMode(CORNER) after matrix pop

See AGENTS.md §6.9 for the complete Android cross-platform trap list.

---

📜 License

MIT License — see LICENSE for details.

---

🙏 Acknowledgements

• SkiaSharp — 2D graphics rendering
• NLua + KeraLua — Lua scripting
• Aether.Physics2D — 2D physics engine
• SDL2 — Windowing and input (Windows)
• p5engine — Architectural inspiration

---

Last updated: 2026-06-02
Current tag: incubation-0.0.23