RuntimeTypeInspector.js: Add RTI build target + Examples integration

examples/package.json

@@ -13,6 +13,7 @@
     "build:thumbnails": "node ./scripts/thumbnails.mjs",
     "clean": "node ./scripts/clean.mjs",
     "develop": "cross-env NODE_ENV=development concurrently --kill-others \"npm run watch\" \"npm run serve\"",
+    "develop:rti": "RTI=on npm run develop",
     "lint": "eslint --ext .js,.mjs .",
     "serve": "serve dist -l 5000 --no-request-logging --config ../serve.json",
     "watch": "npm run -s build:pre && cross-env NODE_ENV=development rollup -c -w"

examples/rollup.config.js → examples/rollup.config.mjs

@@ -15,13 +15,15 @@ import { generateStandalone } from './utils/plugins/rollup-generate-standalone.m
 // engine rollup utils
 import { treeshakeIgnore } from '../utils/plugins/rollup-treeshake-ignore.mjs';
 import { buildTarget } from '../utils/rollup-build-target.mjs';
+import { buildTargetRTI } from '../utils/rollup-build-target-rti.mjs';
 
 // util functions
 import { isModuleWithExternalDependencies } from './utils/utils.mjs';
 
 const NODE_ENV = process.env.NODE_ENV ?? '';
 const ENGINE_PATH = !process.env.ENGINE_PATH && NODE_ENV === 'development' ?
     '../src/index.js' : process.env.ENGINE_PATH ?? '';
+const { RTI = '' } = process.env;
 
 const STATIC_FILES = [
     // static main page src
@@ -95,6 +97,9 @@ function getEngineTargets() {
     checkAppEngine();
 
     const targets = [];
+    if (RTI === 'on') {
+        targets.push(buildTargetRTI('es', '../src/index.rti.js', 'dist/iframe/ENGINE_PATH'));
+    }
     if (ENGINE_PATH) {
         return targets;
     }
@@ -148,7 +153,7 @@ export default [
             skipWrite: true
         },
         treeshake: false,
-        plugins: [generateStandalone(NODE_ENV, ENGINE_PATH), copyStatic(NODE_ENV, STATIC_FILES)]
+        plugins: [generateStandalone(NODE_ENV, ENGINE_PATH, RTI), copyStatic(NODE_ENV, STATIC_FILES)]
     },
     {
         // A debug build is ~2.3MB and a release build ~0.6MB

examples/scripts/standalone-html.mjs

@@ -40,7 +40,10 @@ function generateExampleFile(categoryKebab, exampleNameKebab, setEngineType, fil
 
     // engine
     const engineType = process.env.ENGINE_PATH ? 'development' : process.env.NODE_ENV === 'development' ? 'debug' : setEngineType;
-    const engine = engineFor(engineType);
+    let engine = engineFor(engineType);
+    if (process.env.RTI === 'on') {
+        engine = './ENGINE_PATH/playcanvas.rti.mjs';
+    }
     html = html.replace(/'@ENGINE'/g, JSON.stringify(engine));
 
     if (/'@([A-Z0-9_]+)'/g.test(html)) {

examples/utils/plugins/rollup-generate-standalone.mjs

@@ -10,9 +10,10 @@ const GREEN_OUT = '\x1b[32m';
  *
  * @param {string} nodeEnv - The node environment.
  * @param {string} enginePath - The path to the engine.
+ * @param {string} rti - Whether to activate RuntimeTypeInspector.
  * @returns {import('rollup').Plugin} The plugin.
  */
-export function generateStandalone(nodeEnv, enginePath) {
+export function generateStandalone(nodeEnv, enginePath, rti) {
     return {
         name: 'generate-standalone',
         buildStart() {
@@ -23,7 +24,7 @@ export function generateStandalone(nodeEnv, enginePath) {
             }
         },
         buildEnd() {
-            const cmd = `cross-env NODE_ENV=${nodeEnv} ENGINE_PATH=${enginePath} node ./scripts/standalone-html.mjs`;
+            const cmd = `cross-env NODE_ENV=${nodeEnv} ENGINE_PATH=${enginePath} RTI=${rti} node ./scripts/standalone-html.mjs`;
             console.log(`${GREEN_OUT}${cmd}`);
             execSync(cmd);
         }

package.json

@@ -112,6 +112,7 @@
     "@rollup/plugin-strip": "^3.0.4",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/pluginutils": "^5.1.0",
+    "@runtime-type-inspector/plugin-rollup": "^3.2.6",
     "c8": "^9.1.0",
     "chai": "^5.1.0",
     "eslint": "^8.57.0",
@@ -150,6 +151,7 @@
     "build:treenet": "npm run build target:umd treenet",
     "build:treesun": "npm run build target:umd treesun",
     "build:sourcemaps": "npm run build -- -m",
+    "build:rti": "rollup -c --environment target:rti",
     "watch": "npm run build -- -w",
     "watch:release": "npm run build target:release -- -w",
     "watch:debug": "npm run build target:debug -- -w",

rollup.config.mjs

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs';
 import { version, revision } from './utils/rollup-version-revision.mjs';
 import { buildTarget } from './utils/rollup-build-target.mjs';
+import { buildTargetRTI } from './utils/rollup-build-target-rti.mjs';
 
 // unofficial package plugins
 import dts from 'rollup-plugin-dts';
@@ -103,6 +104,11 @@ BUILD_TYPES.forEach((buildType) => {
     });
 });
 
+if (envTarget === 'rti') {
+    targets.length = 0;
+    targets.push(buildTargetRTI('umd'), buildTargetRTI('es'));
+}
+
 if (envTarget === null || envTarget === 'types') {
     targets.push(...TYPES_TARGET);
 }

src/framework/anim/binder/anim-binder.js

@@ -54,7 +54,7 @@ class AnimBinder {
      * or string path.
      * @returns {string} The locator encoded as a string.
      * @example
-     * // returns 'spotLight/light/color.r'
+     * // returns 'spotLight/light/color/r'
      * encode(['spotLight'], 'light', ['color', 'r']);
      */
     static encode(entityPath, component, propertyPath) {

src/index.rti.js

@@ -0,0 +1,77 @@
+export * from './index.js';
+import { Vec2 } from './core/math/vec2.js';
+import { Vec3 } from './core/math/vec3.js';
+import { Vec4 } from './core/math/vec4.js';
+import { Quat } from './core/math/quat.js';
+import { Mat3 } from './core/math/mat3.js';
+import { Mat4 } from './core/math/mat4.js';
+import { customTypes, customValidations, validateNumber } from '@runtime-type-inspector/runtime';
+import 'display-anything/src/style.js';
+Object.assign(customTypes, {
+    AnimSetter(value) {
+        // Fix for type in ./framework/anim/evaluator/anim-target.js
+        // The AnimSetter type is not sufficient, just patching in the correct type here
+        if (value instanceof Function) {
+            return true;
+        }
+        return value?.set instanceof Function && value?.set instanceof Function;
+    },
+    AnimBinder(value) {
+        // Still using: @implements {AnimBinder}
+        // RTI doesn't take notice of that so far and we started removing `@implements` aswell:
+        // Testable via graphics/contact-hardening-shadows example.
+        return value?.constructor?.name?.endsWith('Binder');
+    },
+    ComponentData(value) {
+        // Used in src/framework/components/collision/trigger.js
+        // Why do we neither use @implements nor `extends` for such type?
+        // Testable via animation/locomotion example.
+        return value?.constructor?.name?.endsWith("ComponentData");
+    },
+    Renderer(value) {
+        // E.g. instance of `ForwardRenderer`
+        return value?.constructor?.name?.endsWith("Renderer");
+    },
+    IArguments(value) {
+        // Used in src/core/tags.js
+        // Testable via physics/offset-collision example.
+        return value[Symbol.iterator] instanceof Function;
+    }
+});
+// For quickly checking props of Vec2/Vec3/Vec4/Quat/Mat3/Mat4 without GC
+const propsXY   = ['x', 'y'];
+const propsXYZ  = ['x', 'y', 'z'];
+const propsXYZW = ['x', 'y', 'z', 'w'];
+const props9    = [0, 1, 2, 3, 4, 5, 6, 7, 8];
+const props16   = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+/**
+ * `@ignoreRTI`
+ * @param {any} value - The value.
+ * @returns {boolean} Only false if we can find some NaN issues.
+ */
+function validate(value) {
+    /**
+     * @param {string|number} prop - Something like 'x', 'y', 'z', 'w', 0, 1, 2, 3, 4 etc.
+     * @returns {boolean} Wether prop is a valid number.
+     */
+    const checkProp = (prop) => {
+        return validateNumber(value, prop);
+    };
+    if (value instanceof Vec2) {
+        return propsXY.every(checkProp);
+    }
+    if (value instanceof Vec3) {
+        return propsXYZ.every(checkProp);
+    }
+    if ((value instanceof Vec4) || (value instanceof Quat)) {
+        return propsXYZW.every(checkProp);
+    }
+    if (value instanceof Mat3) {
+        return props9.every(prop => validateNumber(value.data, prop));
+    }
+    if (value instanceof Mat4) {
+        return props16.every(prop => validateNumber(value.data, prop));
+    }
+    return true;
+}
+customValidations.push(validate);

utils/rollup-build-target-rti.mjs

@@ -0,0 +1,54 @@
+import resolve from '@rollup/plugin-node-resolve';
+import { engineLayerImportValidation } from './plugins/rollup-import-validation.mjs';
+import { getBanner } from './rollup-get-banner.mjs';
+import { runtimeTypeInspector } from '@runtime-type-inspector/plugin-rollup';
+
+/** @typedef {import('rollup').RollupOptions} RollupOptions */
+/** @typedef {import('rollup').OutputOptions} OutputOptions */
+/** @typedef {import('rollup').ModuleFormat} ModuleFormat */
+/** @typedef {import('@rollup/plugin-babel').RollupBabelInputPluginOptions} RollupBabelInputPluginOptions */
+/** @typedef {import('@rollup/plugin-strip').RollupStripOptions} RollupStripOptions */
+
+/**
+ * Configure a Runtime Type Inspector target that rollup is supposed to build.
+ *
+ * @param {'umd'|'es'} moduleFormat - The module format (subset of ModuleFormat).
+ * @param {string} input - The input file.
+ * @param {string} buildDir - The build dir.
+ * @returns {RollupOptions} Configuration for Runtime Type Inspector rollup target.
+ */
+function buildTargetRTI(moduleFormat, input = 'src/index.rti.js', buildDir = 'build') {
+    const banner = getBanner(' (RUNTIME-TYPE-INSPECTOR)');
+
+    const outputExtension = {
+        umd: '.js',
+        es: '.mjs'
+    };
+
+    const file = `${buildDir}/playcanvas.rti${outputExtension[moduleFormat]}`;
+
+    /** @type {OutputOptions} */
+    const outputOptions = {
+        banner,
+        format: moduleFormat,
+        indent: '\t',
+        name: 'pc',
+        file
+    };
+
+    return {
+        input,
+        output: outputOptions,
+        plugins: [
+            engineLayerImportValidation(input, true),
+            resolve(),
+            runtimeTypeInspector({
+                ignoredFiles: [
+                    'node_modules',
+                    'framework/parsers/draco-worker.js' // runs in Worker context without RTI
+                ]
+            })
+        ]
+    };
+}
+export { buildTargetRTI };