scaffold ARToolKit plugin with initial setup and basic functionality

Author: kalwalt

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Install
+        run: npm ci
+      - name: Run tests
+        run: npm test

.gitignore

@@ -137,3 +137,6 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# jetbrains IDEs files
+.idea/

.nvmrc

@@ -0,0 +1 @@
+v22.21.1

README.md

@@ -1 +1,24 @@
-# arjs-plugin-artoolkit
+# arjs-plugin-artoolkit
+```markdown
+# @ar-js-org/arjs-plugin-artoolkit
+
+Minimal ARToolKit detection plugin scaffold for AR.js core.
+
+## Usage
+
+Register with the Engine plugin manager:
+
+```js
+import { ArtoolkitPlugin } from '@ar-js-org/arjs-plugin-artoolkit';
+
+engine.pluginManager.register('artoolkit', new ArtoolkitPlugin({ /* options */ }));
+await engine.pluginManager.enable('artoolkit');
+```
+
+The plugin emits events on the engine event bus:
+- `ar:markerFound`
+- `ar:markerUpdated`
+- `ar:markerLost`
+
+This repo contains a skeleton. Detection and worker/WASM integration will be implemented in follow-up work.
+```

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ar-js-org/arjs-plugin-artoolkit",
+  "version": "0.1.0",
+  "description": "ARToolKit detection plugin for AR.js core (ECS plugin)",
+  "main": "dist/index.js",
+  "module": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "echo \"build step (none yet)\"",
+    "test": "vitest",
+    "lint": "eslint . --ext .js",
+    "prepare": "husky install"
+  },
+  "keywords": [
+    "arjs",
+    "artoolkit",
+    "ar",
+    "plugin"
+  ],
+  "author": "AR.js contributors",
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^9.39.0",
+    "husky": "^9.1.7",
+    "vitest": "^4.0.6"
+  }
+}

src/index.js

@@ -0,0 +1,2 @@
+export { ArtoolkitPlugin } from './plugin.js';
+export { convertModelViewToThreeMatrix } from './utils/matrix.js';

src/plugin.js

@@ -0,0 +1,47 @@
+/**
+ * Minimal ARToolKit plugin skeleton.
+ * Conforms to the Engine Plugin contract: init(core), enable(), disable(), dispose()
+ * Emits events via core.eventBus: 'ar:markerFound', 'ar:markerUpdated', 'ar:markerLost'
+ */
+export class ArtoolkitPlugin {
+    constructor(options = {}) {
+        this.options = options;
+        this.core = null;
+        this.enabled = false;
+        this._onUpdate = null;
+    }
+
+    async init(core) {
+        this.core = core;
+        // load resources if needed
+        return this;
+    }
+
+    async enable() {
+        if (!this.core) throw new Error('Plugin not initialized');
+        this.enabled = true;
+        this._onUpdate = (payload) => this._onFrameUpdate(payload);
+        this.core.eventBus.on('engine:update', this._onUpdate);
+        return this;
+    }
+
+    async disable() {
+        this.enabled = false;
+        if (this._onUpdate) this.core.eventBus.off('engine:update', this._onUpdate);
+        return this;
+    }
+
+    dispose() {
+        return this.disable();
+    }
+
+    _onFrameUpdate({ deltaTime, context }) {
+        // stub: read frame from context/resources and run detection
+        // when detection occurs, emit:
+        // this.core.eventBus.emit('ar:markerFound', { id, poseMatrix, confidence, corners });
+    }
+
+    getMarkerState(markerId) {
+        return null;
+    }
+}

src/utils/matrix.js

@@ -0,0 +1,9 @@
+// small set of conversion helpers for ARToolKit → Three.js coordinate conventions
+export function convertModelViewToThreeMatrix(modelViewArray) {
+    // Input: Float32Array(16) from artoolkit (row-major or library-specific)
+    // Output: Float32Array(16) ready to use with THREE.Matrix4.fromArray (column-major)
+    // Concrete conversion will be implemented when integrating artoolkit5-js.
+    const out = new Float32Array(16);
+    for (let i = 0; i < 16; i++) out[i] = modelViewArray[i];
+    return out;
+}

tests/matrix.test.js

@@ -0,0 +1,11 @@
+import { describe, it, expect } from 'vitest';
+import { convertModelViewToThreeMatrix } from '../src/utils/matrix.js';
+
+describe('matrix utils', () => {
+    it('returns a Float32Array of length 16', () => {
+        const inArr = new Float32Array(16).fill(0);
+        const out = convertModelViewToThreeMatrix(inArr);
+        expect(out).toBeInstanceOf(Float32Array);
+        expect(out.length).toBe(16);
+    });
+});