{"id":27394558,"url":"https://github.com/ignitionai/ignition","last_synced_at":"2026-05-01T04:41:33.920Z","repository":{"id":287564736,"uuid":"965134596","full_name":"IgnitionAI/ignition","owner":"IgnitionAI","description":"Monorepo for the IgnitionAI Framework","archived":false,"fork":false,"pushed_at":"2025-04-12T14:24:13.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-12T14:43:14.873Z","etag":null,"topics":["ai","tensorflowjs","three-js","web","web-ai"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IgnitionAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-12T13:44:07.000Z","updated_at":"2025-04-12T14:24:17.000Z","dependencies_parsed_at":"2025-04-12T14:53:27.336Z","dependency_job_id":null,"html_url":"https://github.com/IgnitionAI/ignition","commit_stats":null,"previous_names":["ignitionai/ignition"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IgnitionAI%2Fignition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IgnitionAI%2Fignition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IgnitionAI%2Fignition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IgnitionAI%2Fignition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IgnitionAI","download_url":"https://codeload.github.com/IgnitionAI/ignition/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248794567,"owners_count":21162613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","tensorflowjs","three-js","web","web-ai"],"created_at":"2025-04-13T22:45:39.072Z","updated_at":"2026-05-01T04:41:33.908Z","avatar_url":"https://github.com/IgnitionAI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IgnitionAI\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)\n[![Tests](https://img.shields.io/badge/tests-184%20passing-22c55e?style=flat-square)](https://github.com/IgnitionAI/ignition/actions)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square)](https://www.typescriptlang.org/)\n\n\u003e **The ML-Agents of the JavaScript creative ecosystem.**\n\u003e Train reinforcement learning agents directly in the browser. Deploy anywhere via ONNX.\n\nIgnitionAI is an open-source RL framework built for creative developers working with **Three.js**, **React Three Fiber**, and the broader JS/TS stack. Describe your world in a class, call `env.train('dqn')`, and watch your agent learn in real time — no Python, no server, no GPU cluster.\n\n---\n\n## Why IgnitionAI?\n\nUnity has [ML-Agents](https://github.com/Unity-Technologies/ml-agents). Python has Stable Baselines, RLlib, CleanRL. JavaScript had nothing comparable — until now.\n\n- **Zero config.** Implement 5 methods, call `train()`. The framework figures out the neural network, hyperparameters, and training loop.\n- **Browser-native.** TensorFlow.js with WebGPU \u003e WebGL \u003e WASM \u003e CPU auto-selection. No install, no CUDA, no server.\n- **Train → Deploy pipeline.** Train in JS, export to ONNX, deploy in Unity (Sentis), Unreal (NNE), Python, C++, or edge devices.\n- **Three.js / R3F first.** Built for the JS creative stack. Pair it with your 3D scene and watch your agent learn in 3D.\n- **Production-ready.** TypeScript strict mode, Zod validation, 184+ tests, CI/CD, modular monorepo.\n\n---\n\n## Install\n\nOne package. Everything included.\n\n```bash\nnpm install ignitionai\n# or\npnpm add ignitionai\n```\n\n---\n\n## Quick Start (7 lines)\n\n```ts\nimport { IgnitionEnvTFJS, CartPoleEnv } from 'ignitionai';\n\nconst cartpole = new CartPoleEnv();\nconst env = new IgnitionEnvTFJS(cartpole);\n\nenv.train('dqn');      // Zero config. It just works.\n// env.infer();        // Switch to inference after training.\n// env.setSpeed(50);   // Turbo training (50x faster).\n```\n\nThat's it. The agent starts learning. The pole stays up.\n\n---\n\n## Define Your Own Environment\n\nDescribe your game world by implementing the `TrainingEnv` interface — 5 methods and an `actions` property.\n\n```ts\nimport { IgnitionEnvTFJS, TrainingEnv } from 'ignitionai';\n\nclass MyGame implements TrainingEnv {\n  // What the agent can do\n  actions = ['left', 'right', 'jump', 'shoot'];\n\n  // What the agent sees (normalized to [-1, 1] ideally)\n  observe(): number[] {\n    return [\n      player.x / WORLD_WIDTH,\n      player.y / WORLD_HEIGHT,\n      enemy.x / WORLD_WIDTH,\n      enemy.y / WORLD_HEIGHT,\n    ];\n  }\n\n  // What happens when the agent acts\n  step(action: number): void {\n    player.do(this.actions[action]);\n  }\n\n  // Is that good or bad?\n  reward(): number {\n    if (player.hitEnemy) return -10;\n    if (player.collectedCoin) return +5;\n    return -distance(player, nearestCoin) * 0.01;\n  }\n\n  // Is the episode over?\n  done(): boolean {\n    return !player.alive || player.won;\n  }\n\n  // Reset the world for a new episode\n  reset(): void {\n    game.restart();\n  }\n}\n\nconst env = new IgnitionEnvTFJS(new MyGame());\nenv.train();  // DQN with sensible defaults\n```\n\nThe framework **deduces** `inputSize` from your first `observe()` call and `actionSize` from `actions.length`. You never touch neural network code.\n\n---\n\n## Algorithms\n\nSwitch algorithms with one word:\n\n```ts\nenv.train('dqn');      // Deep Q-Network — discrete actions, replay buffer\nenv.train('ppo');      // Proximal Policy Optimization — on-policy, stable\nenv.train('qtable');   // Tabular Q-Learning — small discrete state spaces\n```\n\n| Algorithm | Type | Best for |\n|---|---|---|\n| **DQN** | Value-based, off-policy | Most discrete-action problems. Good default. |\n| **PPO** | Policy gradient, on-policy | Complex policies, stability-critical training. |\n| **Q-Table** | Tabular | Small, fully-observable grid worlds. |\n\nYou can override hyperparameters if you want fine control:\n\n```ts\nenv.train('dqn', { lr: 0.0005, hiddenLayers: [128, 128, 64] });\n```\n\n---\n\n## Train in the Browser, Deploy Everywhere\n\nThe ONNX bridge is what makes IgnitionAI a serious tool, not a toy:\n\n```ts\nimport { saveForOnnxExport } from 'ignitionai';\n\n// 1. Train in the browser\nenv.train('dqn');\n// ... wait for convergence ...\nenv.stop();\n\n// 2. Export to ONNX\nconst { conversionScript } = await saveForOnnxExport(\n  env.agent.model,\n  './export',\n);\n\n// 3. Run the Python conversion script (one-time)\n// bash convert.sh\n\n// 4. Deploy the .onnx model anywhere:\n//    - Unity via Sentis or Barracuda\n//    - Unreal Engine via NNE\n//    - Python / C++ / Rust via ONNX Runtime\n//    - Mobile / edge devices\n```\n\nYou can also run inference directly in JS using the trained model:\n\n```ts\nimport { OnnxAgent } from 'ignitionai';\n\nconst agent = new OnnxAgent({\n  modelPath: './my-model.onnx',\n  actionSize: 4,\n});\nawait agent.load();\nconst action = await agent.getAction(observation);\n```\n\n---\n\n## Use with React Three Fiber\n\nPair IgnitionAI with your R3F scene — the env describes the logic, your meshes render the state.\n\n```tsx\nimport { Canvas, useFrame } from '@react-three/fiber';\nimport { IgnitionEnvTFJS, TrainingEnv } from 'ignitionai';\nimport { useRef, useEffect } from 'react';\n\nclass GameEnv implements TrainingEnv {\n  actions = ['left', 'right', 'jump'];\n  observe() { return [...]; }\n  step(action) { ... }\n  reward() { return ...; }\n  done() { return ...; }\n  reset() { ... }\n}\n\nfunction Game() {\n  const envRef = useRef\u003cIgnitionEnvTFJS\u003e();\n\n  useEffect(() =\u003e {\n    envRef.current = new IgnitionEnvTFJS(new GameEnv());\n    envRef.current.train('dqn');\n    return () =\u003e envRef.current?.stop();\n  }, []);\n\n  return (\n    \u003cCanvas\u003e\n      \u003cPlayerMesh /\u003e\n      \u003cEnemyMesh /\u003e\n    \u003c/Canvas\u003e\n  );\n}\n```\n\nThe training loop runs independently of the render loop — the agent learns while your scene renders at 60fps.\n\n---\n\n## Save \u0026 Load Models (HuggingFace Hub)\n\n```ts\nimport { HuggingFaceProvider } from 'ignitionai';\n\nconst storage = new HuggingFaceProvider({\n  token: process.env.HF_TOKEN,\n  repoId: 'your-username/your-rl-model',\n});\n\nawait storage.save('my-agent-v1', env.agent.model);\nconst model = await storage.load('my-agent-v1');\n```\n\n---\n\n## Demos\n\nFive interactive demos showing the framework in action. Each one is a full package you can run locally.\n\n### 2D Demos — Canvas + Charts\n\n| Demo | What it shows | Algorithm |\n|---|---|---|\n| **GridWorld** | Agent finds the shortest path in a 7×7 grid | Q-Table, DQN, PPO |\n| **CartPole** | Classic pole-balancing benchmark with Euler physics | DQN, PPO |\n| **MountainCar** | Agent discovers momentum strategy to climb a hill | DQN, PPO |\n\n### 3D Demos — React Three Fiber\n\n| Demo | What it shows | Tech |\n|---|---|---|\n| **CartPole 3D** | Metallic cart and pole, sunset environment, contact shadows | R3F + drei |\n| **Car Circuit** | 3D car learns to drive an oval circuit — chase cam, HUD, minimap, fading trail, 1x–50x speed slider | R3F + drei |\n\n### Run them locally\n\n```bash\ngit clone https://github.com/IgnitionAI/ignition.git\ncd ignition\npnpm install\npnpm -r run build\n\n# Pick your demo:\npnpm --filter demo-gridworld dev       # http://localhost:3001\npnpm --filter demo-cartpole dev        # http://localhost:3002\npnpm --filter demo-mountaincar dev     # http://localhost:3003\npnpm --filter demo-cartpole-3d dev     # http://localhost:3010\npnpm --filter demo-car-circuit dev     # http://localhost:3020\n```\n\nEach demo has: live 3D/2D visualization, Train/Inference/Stop/Reset controls, algorithm picker (DQN/PPO), live reward chart, and a code panel showing the exact API you'd write in your own project.\n\n---\n\n## Packages\n\nIgnitionAI is a pnpm monorepo. The `ignitionai` package is an umbrella that re-exports everything — most users only need that one.\n\n```\nignitionai                  ← single install, everything included\n├── @ignitionai/core           IgnitionEnv, TrainingEnv interface, types\n├── @ignitionai/backend-tfjs   DQN, PPO, Q-Table + IgnitionEnvTFJS\n├── @ignitionai/backend-onnx   OnnxAgent, TF.js → ONNX exporter\n├── @ignitionai/storage        HuggingFace Hub model persistence\n└── @ignitionai/environments   GridWorld, CartPole, MountainCar\n```\n\nYou can also install individual packages if you want fine-grained dependency control.\n\n---\n\n## Training Speed Control\n\nIgnitionAI exposes `env.setSpeed(multiplier)` so you can accelerate training dynamically:\n\n```ts\nenv.train('dqn');\nenv.setSpeed(50);    // Turbo — 50x faster, agent learns in seconds\n// ... agent converges ...\nenv.setSpeed(1);     // Back to real-time for visual inspection\nenv.infer();\n```\n\nUnder the hood: `stepIntervalMs` goes down and `stepsPerTick` batches multiple steps before yielding to the event loop. Visual updates may become choppy at high speeds but training integrity is preserved.\n\n---\n\n## Tips for Good Results\n\n- **Normalize observations** to `[-1, 1]` or `[0, 1]`. Neural networks hate unbounded inputs.\n- **Shape your rewards.** Dense rewards (distance-based) converge faster than sparse rewards (goal-only). Use sparse only when you want to test exploration.\n- **Start simple.** Get DQN working on a small env before scaling up. CartPole is your \"hello world\".\n- **Let it run.** RL is slower than supervised learning. Be patient or crank the speed slider.\n- **Defaults are good defaults.** If training doesn't converge, first check your env logic — not the hyperparameters.\n\n---\n\n## Project Status\n\n**v0.1 — first public release.**\n\n- Core framework: stable\n- Algorithms (DQN, PPO, Q-Table): stable with convergence tests\n- ONNX export: functional (requires Python conversion step)\n- HuggingFace storage: stable\n- 184+ tests passing across all packages\n- CI/CD: GitHub Actions running tests + build on every PR\n\nSee [roadmap.md](./roadmap.md) for what's coming next (SAC, multi-agent, model hub, more demos).\n\n---\n\n## Contributing\n\nContributions are very welcome. If you build creative JS experiences and want better RL tooling, this project is for you.\n\n```bash\ngit clone https://github.com/IgnitionAI/ignition.git\ncd ignition\npnpm install\npnpm -r run build     # build all packages\npnpm -r run test      # run all tests\n```\n\nThe codebase follows:\n\n- **Spec-driven development** — every feature has a spec in `specs/` (see `specs/012-demo-car-circuit/` for an example)\n- **TDD** — write the failing test, make it pass, refactor\n- **TypeScript strict mode** — no `any`, proper types everywhere\n- **Constitution** — see `.specify/memory/constitution.md`\n\n---\n\n## License\n\n[MIT](./LICENSE) — use it for anything, commercial or otherwise. Attribution appreciated but not required.\n\n---\n\nBuilt by [@salim4n](https://github.com/salim4n) / [@IgnitionAI](https://github.com/IgnitionAI)\n\n**Star the repo** ⭐ if you think creative JS devs deserve proper RL tooling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignitionai%2Fignition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fignitionai%2Fignition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignitionai%2Fignition/lists"}