lunchboxjs 0.2.1001-beta.1 → 0.2.1001-beta.2

package/src/core/update.ts

@@ -38,7 +38,7 @@ export const update: Lunch.UpdateCallback = (opts) => {
     }
 
     // prep options
-    const { app, renderer, scene, camera } = opts
+    const { app, renderer, scene } = opts
 
     // BEFORE RENDER
     app.config.globalProperties.lunchbox.beforeRender.forEach((cb) => {
@@ -46,14 +46,14 @@ export const update: Lunch.UpdateCallback = (opts) => {
     })
 
     // RENDER
-    if (renderer && scene && camera) {
+    if (renderer && scene && opts.app.config.globalProperties.lunchbox.camera) {
         if (app.customRender) {
             app.customRender(opts)
         } else {
             renderer.render(
                 toRaw(scene),
-                // opts.app.config.globalProperties.lunchbox.camera!
-                toRaw(camera)
+                opts.app.config.globalProperties.lunchbox.camera
+                // toRaw(camera)
             )
         }
     }
@@ -66,7 +66,7 @@ export const update: Lunch.UpdateCallback = (opts) => {
 
 // before render
 // ====================
-// TODO: document
+/** Obtain callback methods for `onBeforeRender` and `offBeforeRender`. Usually used internally by Lunchbox. */
 export const useBeforeRender = () => {
     return {
         onBeforeRender: inject<typeof onBeforeRender>(Keys.onBeforeRenderKey),
@@ -76,19 +76,25 @@ export const useBeforeRender = () => {
     }
 }
 
-// TODO: document
+/** Run a function before every render.
+ *
+ * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+ * before a render triggered by that `updateSource`. Normally, the function should run every frame.
+ */
 export const onBeforeRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
     useBeforeRender().onBeforeRender?.(cb, index)
 }
 
-// TODO: document
+/** Remove a function from the `beforeRender` callback list. Useful for tearing down functions added
+ * by `onBeforeRender`.
+ */
 export const offBeforeRender = (cb: Lunch.UpdateCallback | number) => {
     useBeforeRender().offBeforeRender?.(cb)
 }
 
 // after render
 // ====================
-// TODO: document
+/** Obtain callback methods for `onAfterRender` and `offAfterRender`. Usually used internally by Lunchbox. */
 export const useAfterRender = () => {
     return {
         onAfterRender: inject<typeof onAfterRender>(Keys.onBeforeRenderKey),
@@ -96,17 +102,25 @@ export const useAfterRender = () => {
     }
 }
 
-// TODO: document
+/** Run a function after every render.
+ *
+ * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+ * after a render triggered by that `updateSource`. Normally, the function should run every frame.
+ */
 export const onAfterRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
     useBeforeRender().onBeforeRender?.(cb, index)
 }
 
-// TODO: document
+/** Remove a function from the `afterRender` callback list. Useful for tearing down functions added
+ * by `onAfterRender`.
+ */
 export const offAfterRender = (cb: Lunch.UpdateCallback | number) => {
     useBeforeRender().offBeforeRender?.(cb)
 }
 
-// TODO: document
+/** Obtain a function used to cancel the current update frame. Use `cancelUpdate` if you wish
+ * to immediately invoke the cancellation function. Usually used internally by Lunchbox.
+ */
 export const useCancelUpdate = () => {
     const frameId = inject<number>(Keys.frameIdKey)
     return () => {
@@ -114,12 +128,14 @@ export const useCancelUpdate = () => {
     }
 }
 
-// TODO: document
+/** Cancel the current update frame. Usually used internally by Lunchbox. */
 export const cancelUpdate = () => {
     useCancelUpdate()?.()
 }
 
-// TODO: document
+/** Obtain a function used to cancel an update source. Use `cancelUpdateSource` if you wish to
+ * immediately invoke the cancellation function. Usually used internally by Lunchbox.
+ */
 export const useCancelUpdateSource = () => {
     const cancel = inject<
         Lunch.App['config']['globalProperties']['watchStopHandle']
@@ -127,7 +143,7 @@ export const useCancelUpdateSource = () => {
     return () => cancel?.()
 }
 
-// TODO: document
+/** Cancel an update source. Usually used internally by Lunchbox. */
 export const cancelUpdateSource = () => {
     useCancelUpdateSource()?.()
 }

package/src/core/updateObjectProp.ts

@@ -58,6 +58,7 @@ export function updateObjectProp({
     }
 
     // change property
+    // first, save as array in case we need to spread it
     if (liveProperty && isNumber(value) && liveProperty.setScalar) {
         // if value is a number and the property has a `setScalar` method, use that
         liveProperty.setScalar(value)
@@ -66,8 +67,21 @@ export function updateObjectProp({
         const nextValueAsArray = Array.isArray(value) ? value : [value]
         ;(target as any)[finalKey].set(...nextValueAsArray)
     } else if (typeof liveProperty === 'function') {
-        // if property is a function, let's try calling it
-        liveProperty.bind(node.instance)(...value)
+        // some function properties are set rather than called, so let's handle them
+        if (
+            finalKey.toLowerCase() === 'onbeforerender' ||
+            finalKey.toLowerCase() === 'onafterrender'
+        ) {
+            ;(target as any)[finalKey] = value
+        } else {
+            if (!Array.isArray(value)) {
+                throw new Error(
+                    'Arguments on a declarative method must be wrapped in an array.\nWorks:\n<example :methodCall="[256]" />\nDoesn\'t work:\n<example :methodCall="256" />'
+                )
+            }
+            // if property is a function, let's try calling it
+            liveProperty.bind(node.instance)(...value)
+        }
 
         // pass the result to the parent
         // const parent = node.parentNode

package/src/index.ts

@@ -2,19 +2,14 @@ import {
     computed,
     createRenderer,
     Component,
+    ComputedRef,
     inject,
     watch,
     reactive,
     Ref,
 } from 'vue'
 import { createNodeOps } from './nodeOps'
-import {
-    ensuredCamera,
-    ensureRenderer,
-    ensuredScene,
-    extend,
-    MiniDom,
-} from './core'
+import { extend, MiniDom } from './core'
 import { components } from './components'
 import { Lunch } from './types'
 
@@ -27,28 +22,58 @@ export * from './keys'
 // Utilities
 export * from './utils/find'
 
-/** The current camera. Often easier to use `useCamera` instead of this. */
-// TODO: update docs
-export const camera = ensuredCamera
-// TODO: update docs
-export const useCamera = () => ensuredCamera()
+/** The current camera as a computed value. */
+export const useCamera = <T extends THREE.Camera = THREE.Camera>() =>
+    inject<ComputedRef<T>>(Keys.appCameraKey)!
+/** Run a function using the current camera when it's present. */
+export const onCameraReady = <T extends THREE.Camera = THREE.Camera>(
+    cb: (camera?: T) => void
+) => {
+    const stopWatch = watch(
+        useCamera<T>(),
+        (newVal) => {
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
+        },
+        { immediate: true }
+    )
+}
 
-/** The current renderer as a computed value. Often easier to use `useRenderer` instead of this. */
-export const renderer = ensureRenderer
+/** The current renderer as a computed value. */
+export const useRenderer = <T extends THREE.Renderer = THREE.WebGLRenderer>() =>
+    inject<ComputedRef<T>>(Keys.appRenderersKey)!
 /** Run a function using the current renderer when it's present. */
-export const useRenderer = () => ensureRenderer()!
+export const onRendererReady = <T extends THREE.Renderer = THREE.Renderer>(
+    cb: (renderer?: T) => void
+) => {
+    const stopWatch = watch(
+        useRenderer<T>(),
+        (newVal) => {
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
+        },
+        { immediate: true }
+    )
+}
 
-/** The current scene. Often easier to use `useScene` instead of this. */
-// TODO: update docs
-export const scene = ensuredScene
+/** The current scene as a computed value. */
+export const useScene = <T extends THREE.Scene = THREE.Scene>() =>
+    inject<ComputedRef<T>>(Keys.appSceneKey)!
 /** Run a function using the current scene when it's present. */
-// TODO: update docs
-export function useScene(callback: (newScene: THREE.Scene) => void) {
-    return watch(
-        scene,
+export const onSceneReady = <T extends THREE.Scene = THREE.Scene>(
+    cb: (scene?: T) => void
+) => {
+    const stopWatch = watch(
+        useScene<T>(),
         (newVal) => {
-            if (!newVal) return
-            callback(newVal.value as THREE.Scene)
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
         },
         { immediate: true }
     )
@@ -116,18 +141,15 @@ export const updateGlobals = (newValue: Partial<Lunch.AppGlobals>) => {
     useUpdateGlobals()?.(newValue)
 }
 
-// TODO: document
-export const useRootNode = () =>
-    inject<MiniDom.RendererRootNode>(Keys.appRootNodeKey)
-
-// TODO: document
+/** Use the current Lunchbox app. Usually used internally by Lunchbox. */
 export const useApp = () => inject<Lunch.App>(Keys.appKey)
 
-// TODO: document
+/** Obtain a list of the start callback functions. Usually used internally by Lunchbox. */
 export const useStartCallbacks = () =>
-    inject<Lunch.UpdateCallback[]>(Keys.startCallbackKey) //[] as Lunch.UpdateCallback[]
+    inject<Lunch.UpdateCallback[]>(Keys.startCallbackKey)
 
-// TODO: document
+/** Run a given callback once when the Lunchbox app starts. Include an index to
+ * splice the callback at that index in the callback queue. */
 export const onStart = (cb: Lunch.UpdateCallback, index = Infinity) => {
     const callbacks = useStartCallbacks()
     if (index === Infinity) {
@@ -137,7 +159,7 @@ export const onStart = (cb: Lunch.UpdateCallback, index = Infinity) => {
     }
 }
 
-// TODO: document
+/** Obtain a list of interactable objects (registered via onClick, onHover, etc events). Usually used internally by Lunchbox. */
 export const useLunchboxInteractables = () =>
     inject<Ref<Lunch.Node[]>>(Keys.lunchboxInteractables)
 

package/src/utils/index.ts

@@ -43,3 +43,13 @@ export const isLunchboxStandardNode = (
 export const isLunchboxRootNode = (node: any): node is Lunch.RootMeta => {
     return node.isLunchboxRootNode
 }
+
+export const waitFor = async (get: () => any) => {
+    let output = get()
+    while (!output) {
+        await new Promise((resolve) => requestAnimationFrame(resolve))
+        output = get()
+        console.log(output)
+    }
+    return output
+}

package/src/core/ensure.ts

@@ -1,16 +0,0 @@
-import { ComputedRef, inject } from 'vue'
-import * as Keys from '../keys'
-
-export const ensuredCamera = <T extends THREE.Camera = THREE.Camera>() =>
-    inject<ComputedRef<T>>(Keys.appCameraKey)!
-
-// ENSURE RENDERER
-// ====================
-export const ensureRenderer = <
-    T extends THREE.Renderer = THREE.WebGLRenderer
->() => inject<ComputedRef<T>>(Keys.appRenderersKey)
-
-// ENSURE SCENE
-// ====================
-export const ensuredScene = <T extends THREE.Scene = THREE.Scene>() =>
-    inject<ComputedRef<T>>(Keys.appSceneKey)