IgnitionAI

The ML-Agents of the JavaScript creative ecosystem. Train reinforcement learning agents directly in the browser. Deploy anywhere via ONNX.

IgnitionAI 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.

---

Why IgnitionAI?

Unity has ML-Agents. Python has Stable Baselines, RLlib, CleanRL. JavaScript had nothing comparable — until now.

• Zero config. Implement 5 methods, call train(). The framework figures out the neural network, hyperparameters, and training loop.
• Browser-native. TensorFlow.js with WebGPU > WebGL > WASM > CPU auto-selection. No install, no CUDA, no server.
• Train → Deploy pipeline. Train in JS, export to ONNX, deploy in Unity (Sentis), Unreal (NNE), Python, C++, or edge devices.
• Three.js / R3F first. Built for the JS creative stack. Pair it with your 3D scene and watch your agent learn in 3D.
• Production-ready. TypeScript strict mode, Zod validation, 184+ tests, CI/CD, modular monorepo.

---

Install

One package. Everything included.

npm install ignitionai
# or
pnpm add ignitionai

---

Quick Start (7 lines)

import { IgnitionEnvTFJS, CartPoleEnv } from 'ignitionai';

const cartpole = new CartPoleEnv();
const env = new IgnitionEnvTFJS(cartpole);

env.train('dqn');      // Zero config. It just works.
// env.infer();        // Switch to inference after training.
// env.setSpeed(50);   // Turbo training (50x faster).

That's it. The agent starts learning. The pole stays up.

---

Define Your Own Environment

Describe your game world by implementing the TrainingEnv interface — 5 methods and an actions property.

import { IgnitionEnvTFJS, TrainingEnv } from 'ignitionai';

class MyGame implements TrainingEnv {
  // What the agent can do
  actions = ['left', 'right', 'jump', 'shoot'];

  // What the agent sees (normalized to [-1, 1] ideally)
  observe(): number[] {
    return [
      player.x / WORLD_WIDTH,
      player.y / WORLD_HEIGHT,
      enemy.x / WORLD_WIDTH,
      enemy.y / WORLD_HEIGHT,
    ];
  }

  // What happens when the agent acts
  step(action: number): void {
    player.do(this.actions[action]);
  }

  // Is that good or bad?
  reward(): number {
    if (player.hitEnemy) return -10;
    if (player.collectedCoin) return +5;
    return -distance(player, nearestCoin) * 0.01;
  }

  // Is the episode over?
  done(): boolean {
    return !player.alive || player.won;
  }

  // Reset the world for a new episode
  reset(): void {
    game.restart();
  }
}

const env = new IgnitionEnvTFJS(new MyGame());
env.train();  // DQN with sensible defaults

The framework deduces inputSize from your first observe() call and actionSize from actions.length. You never touch neural network code.

---

Algorithms

Switch algorithms with one word:

env.train('dqn');      // Deep Q-Network — discrete actions, replay buffer
env.train('ppo');      // Proximal Policy Optimization — on-policy, stable
env.train('qtable');   // Tabular Q-Learning — small discrete state spaces

Algorithm	Type	Best for
DQN	Value-based, off-policy	Most discrete-action problems. Good default.
PPO	Policy gradient, on-policy	Complex policies, stability-critical training.
Q-Table	Tabular	Small, fully-observable grid worlds.

You can override hyperparameters if you want fine control:

env.train('dqn', { lr: 0.0005, hiddenLayers: [128, 128, 64] });

---

Overrides apply when creating an agent. Calling train() without overrides resumes the existing agent; passing overrides for the same existing agent throws instead of silently changing or losing its weights. Create a new runner to start with a new configuration. Switching algorithms creates a new agent.

Q-table observations default to bounds [0, 1] in every dimension. Supply stateLow and stateHigh for other ranges. Each array must match the observation size, with finite values and stateHigh > stateLow. Out-of-range observations are clamped. Loading requires the same dimensions, bins and bounds as the current agent; incompatible or malformed checkpoints leave it unchanged.

Automatic training and inference share one serialized transition stream. stop() cancels future ticks; a transition already started may finish. Changing mode or algorithm waits behind that transition before executing the new mode. Manual step() and inferStep() calls are also serialized. Automatic failures stop the loop and appear in env.lastError; starting a new loop clears it.

Train in the Browser, Deploy Everywhere

Training runs in the browser. ONNX conversion is a separate Node/Python step.

// Browser: call after convergence, and do not resume while saving.
import { DQNAgent } from 'ignitionai';

env.stop();
await env.inferStep(); // Finish behind any training transition already in flight.
if (!(env.agent instanceof DQNAgent)) throw new Error('Expected DQN');
await env.agent.getModel().save('downloads://ignition-dqn');

Keep both downloaded files (ignition-dqn.json and ignition-dqn.weights.bin) together. In Node, register @tensorflow/tfjs-node to enable file:// handlers:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗