@series-inc/rundot-3d-engine 0.3.0

package/docs/systems/TweenSystem.md

@@ -0,0 +1,132 @@
+# TweenSystem
+
+Property animation system with easing functions for smooth transitions.
+
+## Quick Start
+
+```typescript
+import { TweenSystem, Easing } from "@series-ai/rundot-3d-engine/systems"
+
+// Animate object property
+TweenSystem.tween(
+    this,              // Target object
+    "alpha",           // Property name
+    1.0,               // End value
+    0.5,               // Duration (seconds)
+    Easing.easeOutQuad // Easing function
+)
+```
+
+## Common Use Cases
+
+### Fade In/Out
+
+```typescript
+class FadeEffect extends Component {
+    private alpha: number = 0
+    
+    public fadeIn(): void {
+        const tween = TweenSystem.tween(this, "alpha", 1.0, 0.5, Easing.easeInOutQuad)
+        
+        tween.onUpdated((value) => {
+            // Apply alpha to material
+            this.material.opacity = value
+        })
+        
+        tween.onCompleted(() => {
+            console.log("Fade in complete!")
+        })
+    }
+}
+```
+
+### Scale Pop Animation
+
+```typescript
+class Pickup extends Component {
+    private tweenScale: number = 1.0
+    
+    public quickPop(): void {
+        this.tweenScale = 1.0
+        
+        // Pop up
+        const popTween = TweenSystem.tween(this, "tweenScale", 1.35, 0.12, Easing.easeOutQuad)
+        popTween.onUpdated((value) => {
+            this.gameObject.scale.set(value, value, value)
+        })
+        
+        // Then shrink
+        popTween.onCompleted(() => {
+            const shrinkTween = TweenSystem.tween(this, "tweenScale", 0, 0.3, Easing.easeInOutQuad)
+            shrinkTween.onUpdated((value) => {
+                this.gameObject.scale.set(value, value, value)
+            })
+        })
+    }
+}
+```
+
+### Move Object
+
+```typescript
+class Mover extends Component {
+    public moveTo(targetPos: THREE.Vector3, duration: number): void {
+        TweenSystem.tween(this.gameObject.position, "x", targetPos.x, duration, Easing.easeInOutQuad)
+        TweenSystem.tween(this.gameObject.position, "y", targetPos.y, duration, Easing.easeInOutQuad)
+        TweenSystem.tween(this.gameObject.position, "z", targetPos.z, duration, Easing.easeInOutQuad)
+    }
+}
+```
+
+## Easing Functions
+
+```typescript
+Easing.linear           // No easing
+Easing.easeInQuad       // Accelerate
+Easing.easeOutQuad      // Decelerate
+Easing.easeInOutQuad    // Smooth start and end
+Easing.easeInCubic      // Stronger acceleration
+Easing.easeOutCubic     // Stronger deceleration
+Easing.easeInOutCubic   // Smooth cubic
+Easing.spring           // Spring physics
+Easing.easeOutElastic   // Elastic bounce
+Easing.easeOutBack      // Overshoot
+Easing.anticipateOvershoot // Go back then overshoot
+```
+
+## API Overview
+
+### TweenSystem
+- `tween(target, property, endValue, duration, easing)` - Create tween
+- `update(deltaTime)` - Update all tweens (automatic)
+
+### Tween
+- `onUpdated(callback)` - Called each frame with current value
+- `onCompleted(callback)` - Called when tween finishes
+- `cancel()` - Stop tween early
+
+## Patterns
+
+### Chain Tweens
+
+```typescript
+const tween1 = TweenSystem.tween(this, "x", 10, 1, Easing.easeInOutQuad)
+tween1.onCompleted(() => {
+    const tween2 = TweenSystem.tween(this, "y", 5, 1, Easing.easeInOutQuad)
+})
+```
+
+### Parallel Tweens
+
+```typescript
+// Multiple properties at once
+TweenSystem.tween(obj.position, "x", 10, 1, Easing.linear)
+TweenSystem.tween(obj.position, "y", 5, 1, Easing.linear)
+TweenSystem.tween(obj.rotation, "y", Math.PI, 1, Easing.linear)
+```
+
+## Related Systems
+
+- [VenusGame](../core/VenusGame.md) - Updates TweenSystem automatically
+- [Component](../core/Component.md) - Use tweens in components
+

package/docs/systems/UISystem.md

@@ -0,0 +1,73 @@
+# UISystem
+
+UI utilities and loading screen management.
+
+## Quick Start
+
+```typescript
+import { UISystem } from "@series-ai/rundot-3d-engine/systems"
+
+// Show loading screen
+UISystem.showLoadingScreen()
+
+// Hide loading screen
+UISystem.hideLoadingScreen()
+
+// Create UI elements (use standard HTML/CSS)
+const button = document.createElement("button")
+button.textContent = "Click Me"
+button.style.position = "absolute"
+button.style.top = "50%"
+button.style.left = "50%"
+document.body.appendChild(button)
+```
+
+## Common Use Cases
+
+### Loading Screen
+
+```typescript
+class MyGame extends VenusGame {
+    protected async onStart(): Promise<void> {
+        UISystem.showLoadingScreen()
+        
+        // Load assets
+        await this.loadAssets()
+        
+        UISystem.hideLoadingScreen()
+    }
+}
+```
+
+### HUD Elements
+
+```typescript
+class ScoreDisplay {
+    private scoreElement: HTMLDivElement
+    
+    constructor() {
+        this.scoreElement = document.createElement("div")
+        this.scoreElement.style.position = "absolute"
+        this.scoreElement.style.top = "20px"
+        this.scoreElement.style.right = "20px"
+        this.scoreElement.style.color = "white"
+        this.scoreElement.style.fontSize = "24px"
+        document.body.appendChild(this.scoreElement)
+    }
+    
+    updateScore(score: number): void {
+        this.scoreElement.textContent = `Score: ${score}`
+    }
+}
+```
+
+## API Overview
+
+- `showLoadingScreen()` - Show loading overlay
+- `hideLoadingScreen()` - Hide loading overlay
+- Use standard DOM APIs for custom UI
+
+## Related Systems
+
+- [VenusGame](../core/VenusGame.md) - Game initialization
+

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@series-inc/rundot-3d-engine",
+    "version": "0.3.0",
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "publish": "npm publish",
+        "lint": "eslint src",
+        "lint:fix": "eslint src --fix",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "postinstall": "node scripts/postinstall.mjs"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/series-ai/Run.3DEngine.git",
+        "directory": "."
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        },
+        "./systems": {
+            "types": "./dist/systems/index.d.ts",
+            "import": "./dist/systems/index.js",
+            "require": "./dist/systems/index.cjs"
+        }
+    },
+    "dependencies": {
+        "@dimforge/rapier3d": "^0.11.2",
+        "@dimforge/rapier3d-compat": "^0.11.2",
+        "@stowkit/reader": "^0.1.39",
+        "@stowkit/three-loader": "^0.1.40",
+        "three": "^0.180.0",
+        "three-stdlib": "^2.36.0",
+        "@series-inc/rundot-game-sdk": "5.3.0"
+    },
+    "devDependencies": {
+        "@types/three": "^0.180.0",
+        "@types/node": "^20.11.16",
+        "@typescript-eslint/eslint-plugin": "^8.32.1",
+        "@typescript-eslint/parser": "^8.32.1",
+        "eslint": "^9.39.2",
+        "eslint-import-resolver-typescript": "^4.4.1",
+        "eslint-plugin-import": "^2.31.0",
+        "prettier": "^3.2.4",
+        "tsup": "^8.5.0",
+        "typescript": "^5.3.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "docs",
+        "scripts"
+    ]
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, statSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const docsSource = join(packageRoot, "docs");
+
+if (!existsSync(docsSource)) {
+  process.exit(0);
+}
+
+// Walk up from the package root to find the consuming project root.
+// If we're inside node_modules, exit out of it. Otherwise (e.g. local dev), use packageRoot.
+function findProjectRoot() {
+  let dir = packageRoot;
+  while (true) {
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    const baseName = dir.split(/[\\/]/).pop();
+    if (baseName === "node_modules") {
+      return parent;
+    }
+    dir = parent;
+  }
+  // Not inside node_modules — running locally in the package itself
+  return packageRoot;
+}
+
+const projectRoot = findProjectRoot();
+const docsDest = join(projectRoot, ".rundot", "3d-engine-docs");
+
+// Remove existing docs to keep them in sync
+if (existsSync(docsDest)) {
+  rmSync(docsDest, { recursive: true, force: true });
+}
+
+function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+copyDir(docsSource, docsDest);