feat: add new “animate” event for distance based animation throttling

Works the same way “update” does, but apps that are far away from the camera will have “animate” called much less often, for a big performance boost.

Author: ashconnell

src/client/public/ai-docs.md

@@ -202,26 +202,28 @@ const box = app.create('prim', {
 
 ## Animation
 
-Only when requested, you can make things move or change over time by hooking into the update cycle:
+Only when requested, you can make things move or change over time by hooking into the animation cycle:
 
 ```jsx
-app.on('update', delta => {
+app.on('animate', delta => {
   box.rotation.y += 45 * DEG2RAD * delta // rotate around Y axis each frame 45 degrees per second
 })
 ```
 
-If something needs to happen in response to interaction (eg triggers or actions), subscribe and unsubscribe only as needed for performance:
+The `animate` rate is dynamic based on how far away the app is from the camera, so be sure to use `delta` time to normalize speeds.
+
+If animations start in response to triggers or actions and have an end time, subscribe and unsubscribe for performance:
 
 ```jsx
-const update = delta => {
+const animate = delta => {
   // do things
 }
 
 // subscribe when something needs to happen
-app.on('update', update)
+app.on('animate', animate)
 
-// unsubscribe when idle to save resources
-app.off('update', update)
+// unsubscribe when finsihed to save resources
+app.off('animate', animate)
 ```
 
 ## Bloom

src/core/World.js

@@ -6,6 +6,7 @@ import { Collections } from './systems/Collections'
 import { Apps } from './systems/Apps'
 import { Anchors } from './systems/Anchors'
 import { Avatars } from './systems/Avatars'
+import { Animation } from './systems/Animation'
 import { Events } from './systems/Events'
 import { Chat } from './systems/Chat'
 import { Blueprints } from './systems/Blueprints'
@@ -40,6 +41,7 @@ export class World extends EventEmitter {
     this.register('apps', Apps)
     this.register('anchors', Anchors)
     this.register('avatars', Avatars)
+    this.register('animation', Animation)
     this.register('events', Events)
     this.register('scripts', Scripts)
     this.register('chat', Chat)

src/core/entities/App.js

@@ -12,7 +12,7 @@ import { Layers } from '../extras/Layers'
 import { createPlayerProxy } from '../extras/createPlayerProxy'
 import { serializeError } from '../extras/serializeError'
 
-const hotEventNames = ['fixedUpdate', 'update', 'lateUpdate']
+const hotEventNames = ['fixedUpdate', 'update', 'animate', 'lateUpdate']
 
 const Modes = {
   ACTIVE: 'active',
@@ -42,6 +42,8 @@ export class App extends Entity {
     this.target = null
     this.projectLimit = Infinity
     this.resetOnMove = false
+    this.animateDelta = 0
+    this.animateRate = 0.001
     this.playerProxies = new Map()
     this.hitResultsPool = []
     this.hitResults = []
@@ -226,10 +228,17 @@ export class App extends Entity {
       this.networkQuat.update(delta)
       this.networkSca.update(delta)
     }
-    // script update()
+    // script update/animate
     if (this.script) {
       try {
+        // update
         this.emit('update', delta)
+        // animate
+        this.animateDelta += delta
+        while (this.animateDelta >= this.animateRate) {
+          this.emit('animate', this.animateDelta)
+          this.animateDelta = 0
+        }
       } catch (err) {
         this.scriptError = serializeError(err)
         console.error('script update() crashed', this)

src/core/systems/Animation.js

@@ -0,0 +1,64 @@
+import { System } from './System'
+import * as THREE from 'three'
+
+const v1 = new THREE.Vector3()
+
+const BATCH_SIZE = 10
+
+/**
+ * Animation System
+ *
+ * - Updates app animation rates based on distance to camera
+ *
+ */
+export class Animation extends System {
+  constructor(world) {
+    super(world)
+    this.apps = []
+    this.cursor = 0
+  }
+
+  init() {
+    this.world.entities.on('added', this.onAdded)
+    this.world.entities.on('removed', this.onRemoved)
+  }
+
+  onAdded = entity => {
+    if (!entity.isApp) return
+    this.apps.push(entity)
+  }
+
+  onRemoved = entity => {
+    if (!entity.isApp) return
+    const idx = this.apps.indexOf(entity)
+    if (idx === -1) return
+    this.apps.splice(idx, 1)
+  }
+
+  update() {
+    if (!this.apps.length) return
+    const camPos = v1.setFromMatrixPosition(this.world.camera.matrixWorld)
+    const batch = Math.min(BATCH_SIZE, this.apps.length)
+    for (let i = 0; i < batch; i++) {
+      const app = this.apps[this.cursor % this.apps.length]
+      if (!app.root) {
+        this.cursor++
+        continue
+      }
+      const appPos = app.root.position
+      const distance = camPos.distanceTo(appPos)
+      if (distance < 30) {
+        app.animateRate = 0.001 // max fps
+      } else if (distance < 80) {
+        app.animateRate = 1 / 30
+      } else {
+        app.animateRate = 1 / 20
+      }
+      this.cursor++
+    }
+  }
+
+  destroy() {
+    this.apps = []
+  }
+}

src/core/systems/Entities.js

@@ -58,7 +58,7 @@ export class Entities extends System {
       this.player = entity
       this.world.emit('player', entity)
     }
-    this.emit('added')
+    this.emit('added', entity)
     return entity
   }
 
@@ -69,7 +69,7 @@ export class Entities extends System {
     entity.destroy()
     this.items.delete(id)
     this.removed.push(id)
-    this.emit('removed')
+    this.emit('removed', entity)
   }
 
   setHot(entity, hot) {