Vite + TS + Multisynq

` is added to the document’s `` by default. 129 | * You can specify a different parent element by its `id` string or DOM element: 130 | * ```js 131 | * Multisynq.App.root = element; // DOM element or id string 132 | * ``` 133 | * **Replacing the default overlay** 134 | * 135 | * To disable the overlay completely set the _App_ root to `false`. 136 | * ```js 137 | * Multisynq.App.root = false; 138 | * ``` 139 | * To show your own overlay, handle the `"synced"` event. 140 | * 141 | * @event synced 142 | * @property {String} scope - [this.viewId]{@link View#viewId} 143 | * @property {String} event - `"synced"` 144 | * @property {Boolean} data - `true` if in sync, `false` if backlogged 145 | * @public 146 | */ 147 | -------------------------------------------------------------------------------- /client/teatime/src/upload.worker.js: -------------------------------------------------------------------------------- 1 | // this is our UploadWorker 2 | 3 | import { deflate } from 'pako/dist/pako_deflate.js'; // eslint-disable-line import/extensions 4 | import Base64 from "crypto-js/enc-base64"; 5 | import AES from "crypto-js/aes"; 6 | import SHA256 from "crypto-js/sha256"; 7 | import WordArray from "crypto-js/lib-typedarrays"; 8 | import HmacSHA256 from "crypto-js/hmac-sha256"; 9 | 10 | // NOTE: if you add a new import, you must also add it to "dependencies" in package.json 11 | // so thet it gets bundled. The "peerDependencies" are not bundled. 12 | 13 | // esbuild will uncomment the line below in the case of a Node.js build 14 | // _IF_NODE_ import * as _WORKER_THREADS from 'worker_threads'; 15 | 16 | /* eslint-disable-next-line */ 17 | const NODE = _IS_NODE_; // replaced by esbuild 18 | 19 | let poster; 20 | let fetcher = fetch; 21 | if (NODE) { 22 | const { parentPort } = _WORKER_THREADS; // imported above 23 | parentPort.on('message', msg => handleMessage({ data: msg })); 24 | poster = msg => parentPort.postMessage({ data: msg }); 25 | } else { 26 | onmessage = handleMessage; 27 | poster = postMessage; 28 | } 29 | 30 | const offlineFiles = new Map(); 31 | 32 | function handleMessage(msg) { 33 | const { job, cmd, server, path: templatePath, buffer, keyBase64, gzip, 34 | referrer, id, appId, persistentId, MULTISYNQ_VERSION, debug, what, offline } = msg.data; 35 | if (offline) fetcher = offlineStore; 36 | switch (cmd) { 37 | case "uploadEncrypted": uploadEncrypted(templatePath); break; 38 | case "getOfflineFile": getOfflineFile(msg.data.url); break; 39 | default: console.error("Unknown worker command", cmd); 40 | } 41 | 42 | function encrypt(bytes) { 43 | const start = Date.now(); 44 | const plaintext = WordArray.create(bytes); 45 | const key = Base64.parse(keyBase64); 46 | const hmac = HmacSHA256(plaintext, key); 47 | const iv = WordArray.random(16); 48 | const { ciphertext } = AES.encrypt(plaintext, key, { iv }); 49 | // Version 0 used Based64: 50 | // const encrypted = "CRQ0" + [iv, hmac, ciphertext].map(wordArray => wordArray.toString(Base64)).join(''); 51 | // Version 1 is binary: 52 | const encrypted = new ArrayBuffer(4 + iv.sigBytes + hmac.sigBytes + ciphertext.sigBytes); 53 | const view = new DataView(encrypted); 54 | let i = 0; 55 | view.setUint32(i, 0x43525131, false); i += 4; //"CRQ1" 56 | // CryptoJS WordArrays are big-endian 57 | for (const array of [iv, hmac, ciphertext]) { 58 | for (const word of array.words) { 59 | view.setInt32(i, word, false); i += 4; 60 | } 61 | } 62 | if (debug) console.log(id, `${what} encrypted (${encrypted.byteLength} bytes) in ${Date.now() - start}ms`); 63 | return encrypted; 64 | } 65 | 66 | function compress(bytes) { 67 | const start = Date.now(); 68 | const compressed = deflate(bytes, { gzip: true, level: 1 }); // sloppy but quick 69 | if (debug) console.log(id, `${what} compressed (${compressed.length} bytes) in ${Date.now() - start}ms`); 70 | return compressed; 71 | } 72 | 73 | function hash(bytes) { 74 | const start = Date.now(); 75 | const sha256 = SHA256(WordArray.create(bytes)); 76 | const base64 = Base64.stringify(sha256); 77 | const base64url = base64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_"); 78 | if (debug) console.log(id, `${what} hashed (${bytes.byteLength} bytes) in ${Date.now() - start}ms`); 79 | return base64url; 80 | } 81 | 82 | async function getUploadUrl(path) { 83 | if (offline) { 84 | const url = `offline:///${path}`; 85 | return { url, uploadUrl: url }; 86 | } 87 | const start = Date.now(); 88 | const url = `${server.url}/${path}`; 89 | if (!server.apiKey) return { url, uploadUrl: url }; 90 | 91 | const response = await fetcher(url, { 92 | headers: { 93 | "X-Croquet-Auth": server.apiKey, 94 | "X-Croquet-App": appId, 95 | "X-Croquet-Id": persistentId, 96 | "X-Croquet-Session": id, 97 | "X-Croquet-Version": MULTISYNQ_VERSION, 98 | "X-Croquet-Path": (new URL(referrer)).pathname, 99 | }, 100 | referrer 101 | }); 102 | 103 | const { ok, status, statusText } = response; 104 | if (!ok) throw Error(`Error in signing URL: ${status} - ${statusText}`); 105 | 106 | const { error, read, write } = await response.json(); 107 | if (error) throw Error(error); 108 | if (debug) console.log(id, `${what} upload authorized in ${Date.now() - start}ms`); 109 | return { url: read, uploadUrl: write }; 110 | } 111 | 112 | async function uploadEncrypted(path) { 113 | try { 114 | let body = encrypt(gzip ? compress(buffer) : buffer); 115 | if (NODE) body = new Uint8Array(body); // buffer needs to be put in an array 116 | if (path.includes("%HASH%")) path = path.replace("%HASH%", hash(body)); 117 | const { uploadUrl, url } = await getUploadUrl(path); 118 | const start = Date.now(); 119 | const { ok, status, statusText } = await fetcher(uploadUrl, { 120 | method: "PUT", 121 | mode: "cors", 122 | headers: { "Content-Type": "application/octet-stream" }, 123 | referrer, 124 | body 125 | }); 126 | if (!ok) throw Error(`server returned ${status} ${statusText} for PUT ${uploadUrl}`); 127 | if (debug) console.log(id, `${what} uploaded (${status}) in ${Date.now() - start}ms ${url}`); 128 | poster({ job, url, ok, status, statusText, bytes: NODE ? body.length : body.byteLength }); 129 | } catch (e) { 130 | if (debug) console.error(`${id} upload error ${e.message}`); 131 | poster({ job, ok: false, status: -1, statusText: e.message }); 132 | } 133 | } 134 | 135 | function offlineStore(requestUrl, options) { 136 | if (debug) console.log(id, `storing ${requestUrl}`); 137 | offlineFiles.set(requestUrl, options.body); 138 | return { ok: true, status: 201, statusText: "Offline created" }; 139 | } 140 | 141 | function getOfflineFile(requestUrl) { 142 | const body = offlineFiles.get(requestUrl); 143 | if (!body) { 144 | if (debug) console.error(`${id} file not found ${requestUrl}`); 145 | poster({ job, ok: false, status: -1, statusText: "Offline file not found" }); 146 | return; 147 | } 148 | if (debug) console.log(id, `retrieved ${requestUrl}`); 149 | poster({ job, ok: true, status: 200, statusText: "Offline file found", body, bytes: NODE ? body.length : body.byteLength }); 150 | } 151 | } 152 | -------------------------------------------------------------------------------- /client/teatime/thirdparty-patched/seedrandom/seedrandom.js: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2019 David Bau. 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining 5 | a copy of this software and associated documentation files (the 6 | "Software"), to deal in the Software without restriction, including 7 | without limitation the rights to use, copy, modify, merge, publish, 8 | distribute, sublicense, and/or sell copies of the Software, and to 9 | permit persons to whom the Software is furnished to do so, subject to 10 | the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be 13 | included in all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 18 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 19 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 20 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 21 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 22 | 23 | Patched 2025 by Croquet Labs to: 24 | - remove import of `crypto` module 25 | - use ES6 module syntax. 26 | - remove Math patching 27 | - remove global entropy pool and autoseeding 28 | - remove unused code 29 | 30 | */ 31 | 32 | // 33 | // The following constants are related to IEEE 754 limits. 34 | // 35 | 36 | var width = 256, // each RC4 output is 0 <= x < 256 37 | chunks = 6, // at least six RC4 outputs for each double 38 | digits = 52, // there are 52 significant digits in a double 39 | startdenom = Math.pow(width, chunks), 40 | significance = Math.pow(2, digits), 41 | overflow = significance * 2, 42 | mask = width - 1; 43 | 44 | // 45 | // seedrandom() 46 | // 47 | function seedrandom(seed, options) { 48 | var key = []; 49 | options = options || {}; 50 | 51 | if (options.entropy) throw new Error('this version of seedrandom does not support entropy'); 52 | if (seed == null && !options.state) throw new Error('this version of seedrandom requires a seed'); 53 | 54 | // Flatten the seed string 55 | mixkey(flatten(seed, 3), key); 56 | 57 | // Use the seed to initialize an ARC4 generator. 58 | var arc4 = new ARC4(key); 59 | 60 | // This function returns a random double in [0, 1) that contains 61 | // randomness in every bit of the mantissa of the IEEE 754 value. 62 | var prng = function() { 63 | var n = arc4.g(chunks), // Start with a numerator n < 2 ^ 48 64 | d = startdenom, // and denominator d = 2 ^ 48. 65 | x = 0; // and no 'extra last byte'. 66 | while (n < significance) { // Fill up all significant digits by 67 | n = (n + x) * width; // shifting numerator and 68 | d *= width; // denominator and generating a 69 | x = arc4.g(1); // new least-significant-byte. 70 | } 71 | while (n >= overflow) { // To avoid rounding up, before adding 72 | n /= 2; // last byte, shift everything 73 | d /= 2; // right using integer math until 74 | x >>>= 1; // we have exactly the desired bits. 75 | } 76 | return (n + x) / d; // Form the number within [0, 1). 77 | }; 78 | 79 | prng.int32 = function() { return arc4.g(4) | 0; } 80 | prng.quick = function() { return arc4.g(4) / 0x100000000; } 81 | prng.double = prng; 82 | 83 | return (options.pass || 84 | function(prng, state) { 85 | if (state) { 86 | // Load the arc4 state from the given state if it has an S array. 87 | if (state.S) { copy(state, arc4); } 88 | // Only provide the .state method if requested via options.state. 89 | prng.state = function() { return copy(arc4, {}); } 90 | } 91 | return prng; 92 | })( 93 | prng, 94 | options.state); 95 | } 96 | 97 | // 98 | // ARC4 99 | // 100 | // An ARC4 implementation. The constructor takes a key in the form of 101 | // an array of at most (width) integers that should be 0 <= x < (width). 102 | // 103 | // The g(count) method returns a pseudorandom integer that concatenates 104 | // the next (count) outputs from ARC4. Its return value is a number x 105 | // that is in the range 0 <= x < (width ^ count). 106 | // 107 | function ARC4(key) { 108 | var t, keylen = key.length, 109 | me = this, i = 0, j = me.i = me.j = 0, s = me.S = []; 110 | 111 | // The empty key [] is treated as [0]. 112 | if (!keylen) { key = [keylen++]; } 113 | 114 | // Set up S using the standard key scheduling algorithm. 115 | while (i < width) { 116 | s[i] = i++; 117 | } 118 | for (i = 0; i < width; i++) { 119 | s[i] = s[j = mask & (j + key[i % keylen] + (t = s[i]))]; 120 | s[j] = t; 121 | } 122 | 123 | // The "g" method returns the next (count) outputs as one number. 124 | (me.g = function(count) { 125 | // Using instance members instead of closure state nearly doubles speed. 126 | var t, r = 0, 127 | i = me.i, j = me.j, s = me.S; 128 | while (count--) { 129 | t = s[i = mask & (i + 1)]; 130 | r = r * width + s[mask & ((s[i] = s[j = mask & (j + t)]) + (s[j] = t))]; 131 | } 132 | me.i = i; me.j = j; 133 | return r; 134 | // For robust unpredictability, the function call below automatically 135 | // discards an initial batch of values. This is called RC4-drop[256]. 136 | // See http://google.com/search?q=rsa+fluhrer+response&btnI 137 | })(width); 138 | } 139 | 140 | // 141 | // copy() 142 | // Copies internal state of ARC4 to or from a plain object. 143 | // 144 | function copy(f, t) { 145 | t.i = f.i; 146 | t.j = f.j; 147 | t.S = f.S.slice(); 148 | return t; 149 | }; 150 | 151 | // 152 | // flatten() 153 | // Converts an object tree to nested arrays of strings. 154 | // 155 | function flatten(obj, depth) { 156 | var result = [], typ = (typeof obj), prop; 157 | if (depth && typ == 'object') { 158 | for (prop in obj) { 159 | try { result.push(flatten(obj[prop], depth - 1)); } catch (e) {} 160 | } 161 | } 162 | return (result.length ? result : typ == 'string' ? obj : obj + '\0'); 163 | } 164 | 165 | // 166 | // mixkey() 167 | // Mixes a string seed into a key that is an array of integers, and 168 | // returns a shortened string seed that is equivalent to the result key. 169 | // 170 | function mixkey(seed, key) { 171 | var stringseed = seed + '', smear, j = 0; 172 | while (j < stringseed.length) { 173 | key[mask & j] = 174 | mask & ((smear ^= key[mask & j] * 19) + stringseed.charCodeAt(j++)); 175 | } 176 | return tostring(key); 177 | } 178 | 179 | // 180 | // tostring() 181 | // Converts an array of charcodes to a string 182 | // 183 | function tostring(a) { 184 | return String.fromCharCode.apply(0, a); 185 | } 186 | 187 | export default seedrandom; 188 | -------------------------------------------------------------------------------- /client/teatime/src/messenger.js: -------------------------------------------------------------------------------- 1 | // There are three kinds of messages: 2 | // 1. An app to the container. 3 | // 2. The container to a single app 4 | // 3. The container to all apps 5 | 6 | // The TeaTime framework creates a singleton instance of M and install it to Multisynq.Messenger 7 | // To use the Messenger object, the client needs to set the receiver object for invoking the handler for an incoming message: 8 | // Multisynq.Messenger.setReceiver(this); 9 | 10 | // where "this" is a view side object that handles incoming messages. 11 | 12 | // To listen on an incoming message, the receiver calls: 13 | // Multisynq.Messenger.on(event, callback>); 14 | 15 | // To send a message: 16 | // Multisynq.Messenger.send(event, data, receipent); 17 | 18 | // An app can send a message only to the container so the recipient argument will be ignored. 19 | // The container can send a message to a specific Window by supplying the third argument. 20 | 21 | // When a message is received, the function or the method specified by the method name is invoked with the object provided for the Messenger constructor as "this". 22 | 23 | // The object follows the "structured clone algorithm, but let us say that it should be 24 | // JSONable 25 | 26 | // An example on the container side looks like this (the view class or the expander, is an instance of PasteUpView in this example): 27 | 28 | // init() { 29 | // Multisynq.Messenger.setReceiver(this); 30 | // Multisynq.Messenger.onC"requestUserInfo", "sendUserInfo"); 31 | // } 32 | // 33 | // and aPasteUpView.sendUsernfo looks like: 34 | // sendUserInfo(data, source) { 35 | // const userInfo = this.model._get("userInfo")[this.viewId]; 36 | // Multisynq.Messenger.send("userInfo", userInfo, source); 37 | // // where the last argument specifies that this is a directed message 38 | // } 39 | 40 | // The container needs to be careful what information it sends to an app. 41 | 42 | // On the container side, there is a method called setIframeEnumerator, where Multisynq, of a future container app, specifies a way to enumerate all relevant iframes. 43 | 44 | // For a cursor movement, an app may do: 45 | // Multisynq.Messenger.send("pointerPosition", {x, y}); 46 | 47 | // The container side PasteUpView would have a subscriber: 48 | 49 | // handlePointerMove(data, source) { 50 | // let iframe = this.apps[source]; // this.apps would be a WeakMap 51 | // let translatedPostion = f(iframe.style.transformation... data.x, ... data.y); 52 | // this.pointerMoved(transatedPosition); 53 | // } 54 | 55 | class M { 56 | constructor() { 57 | this.ready = false; 58 | this.isInIframe = window.top !== window; 59 | this.subscriptions = {}; 60 | this.enumerator = null; 61 | } 62 | 63 | setReceiver(receiver) { 64 | this.receiver = receiver; 65 | this.ready = true; 66 | } 67 | 68 | setIframeEnumerator(func) { 69 | this.enumerator = func; 70 | } 71 | 72 | on(event, method) { 73 | if (!this.receiver) {throw Error("setReceiver() has not been called");} 74 | if (typeof method === "string") { 75 | method = this.receiver[method]; 76 | } 77 | 78 | if (!method) {throw Error("Messenger.on: the second argument must be a method name or a function");} 79 | 80 | if (!this.subscriptions[event]) { 81 | this.subscriptions[event] = []; 82 | } else if (this.findIndex(this.subscriptions[event], method) >= 0) { 83 | throw Error(`${method} is already subscribed`); 84 | } 85 | this.subscriptions[event].push(method); 86 | 87 | if (!this.listener) { 88 | this.listener = msg => this.receive(msg); 89 | window.addEventListener("message", this.listener); 90 | } 91 | } 92 | 93 | detach() { 94 | if (this.listener) { 95 | window.removeEventListener("message", this.listener); 96 | this.listener = null; 97 | } 98 | 99 | this.stopPublishingPointerMove(); 100 | 101 | this.receiver = null; 102 | this.subscriptions = {}; 103 | this.enumerator = null; 104 | this.ready = false; 105 | } 106 | 107 | removeSubscription(event, method) { 108 | if (typeof method === "string") { 109 | method = this.receiver[method]; 110 | } 111 | 112 | const handlers = this.subscriptions[event]; 113 | if (handlers) { 114 | const indexToRemove = this.findIndex(handlers, method); 115 | handlers.splice(indexToRemove, 1); 116 | if (handlers.length === 0) delete this.subscriptions[event]; 117 | } 118 | } 119 | 120 | removeAllSubscriptions() { 121 | this.subscriptions = {}; 122 | } 123 | 124 | receive(msg) { 125 | const {event, data} = msg.data; 126 | const source = msg.source; 127 | 128 | this.handleEvent(event, data, source); 129 | } 130 | 131 | handleEvent(event, data, source) { 132 | const handlers = this.subscriptions[event]; 133 | if (!handlers) {return;} 134 | handlers.forEach(handler => { 135 | handler.call(this.receiver, data, source); 136 | }); 137 | } 138 | 139 | send(event, data, directWindow) { 140 | if (this.isInIframe) { 141 | window.top.postMessage({event, data}, "*"); 142 | return; 143 | } 144 | 145 | if (directWindow) { 146 | directWindow.postMessage({event, data}, "*"); 147 | return; 148 | } 149 | 150 | if (!this.enumerator) {return;} 151 | 152 | const iframes = this.enumerator(); 153 | iframes.forEach(iframe => { 154 | iframe.contentWindow.postMessage({event, data}, "*"); 155 | // or we still pass a strong created from iframe as target origin 156 | }); 157 | } 158 | 159 | findIndex(array, method) { 160 | const mName = method.name; 161 | return array.findIndex(entry => { 162 | const eName = entry.name; 163 | if (!mName && !eName) { 164 | // when they are not proxied, a === comparison 165 | // for the case of both being anonymous 166 | return method === entry; 167 | } 168 | // otherwise, compare their names. 169 | // it is okay as the receiver is the same, 170 | // and the client should call removeSubscription if it wants to update the handler 171 | return mName === eName; 172 | }); 173 | } 174 | 175 | startPublishingPointerMove() { 176 | if (this._moveHandler) {return;} 177 | this._moveHandler = evt => this.send("pointerPosition", {x: evt.clientX, y: evt.clientY, type: evt.type}); 178 | window.document.addEventListener("pointermove", this._moveHandler, true); 179 | } 180 | 181 | stopPublishingPointerMove() { 182 | if (this._moveHandler) { 183 | window.document.removeEventListener("pointermove", this._moveHandler, true); 184 | this._moveHandler = null; 185 | } 186 | } 187 | 188 | } 189 | 190 | export const Messenger = new M(); 191 | -------------------------------------------------------------------------------- /esbuild.mjs: -------------------------------------------------------------------------------- 1 | import esbuild from 'esbuild'; 2 | import fs from 'fs'; 3 | import os from 'os'; 4 | import path from 'path'; 5 | import { execSync } from 'child_process'; 6 | import { replace } from 'esbuild-plugin-replace'; 7 | import { nodeExternalsPlugin } from 'esbuild-node-externals'; 8 | import inlineWorkerPlugin from './esbuild-plugin-inline-worker.mjs'; 9 | 10 | // We need a unique version string for each single build because this gets hashed 11 | // into the Session ID instead of the whole library source code. 12 | // The version string is derived from the package.json version and the git commit. 13 | // release: x.y.z 14 | // prerelease: x.y.z-v 15 | // clean tree: x.y.z-v+branch.commit 16 | // otherwise: x.y.z-v+branch.commit.user.date 17 | 18 | const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8')); 19 | const sources = ["./multisynq-client.js", "./client", "./esbuild.mjs"]; // check if these are committed 20 | const git_branch = execSync("git rev-parse --abbrev-ref HEAD").toString().trim(); // current branch 21 | const git_commit = execSync("git log -1 --pretty=format:%H -- .").toString().trim(); // last commit hash 22 | const git_date = execSync("git show --format='%as' -s " + git_commit).toString().trim(); // last commit date 23 | const git_message = execSync("git show --format='%s' -s " + git_commit).toString().trim(); // last commit message 24 | const git_bumped = git_message.endsWith(pkg.version); // last commit was "changelog and version bump to x.y.z" 25 | const git_clean = !execSync("git status --porcelain -- " + sources.join(" ")).toString().trim(); // relevant sources are committed 26 | 27 | const release = !pkg.version.includes('-'); 28 | const prerelease = pkg.version.includes('-') && (git_branch === "main" || git_branch === "dev") && git_bumped && git_clean; 29 | 30 | if (release) { 31 | // if you run into this error while developing, change the version in package.json to a prerelease version x.y.z-v 32 | if (!git_clean) throw Error(`Release build ${pkg.version} but git is not clean`); 33 | if (!git_bumped) throw Error(`Release build ${pkg.version} but not bumped`); 34 | if (git_branch !== "main") throw Error(`Release build ${pkg.version} but not on main branch`); 35 | } 36 | 37 | const date = new Date(); 38 | 39 | const VERSION = release || prerelease ? pkg.version 40 | : git_clean ? `${pkg.version}+${git_branch}.${git_commit}` 41 | : `${pkg.version}+${git_branch}.${git_commit}.${os.userInfo().username}.${date.toISOString()}`; 42 | 43 | console.log(`Building Multisynq ${VERSION}`); 44 | console.log(` bumped: ${git_bumped}, clean: ${git_clean}`); 45 | 46 | // common options for all builds 47 | const COMMON = { 48 | entryPoints: ['multisynq-client.js'], 49 | bundle: true, 50 | sourcemap: true, 51 | minify: true, 52 | banner: { 53 | js: 54 | `// (C) ${git_date.slice(0, 4)} ${pkg.author}\n` + 55 | `// Multisynq Client v${VERSION}\n` + 56 | `// Built on ${date.toISOString()}\n` 57 | }, 58 | }; 59 | 60 | const node_webrtc_import = ` 61 | if (!globalThis.loadingDataChannel) { 62 | globalThis.loadingDataChannel = new Promise(resolve => { 63 | import('node-datachannel/polyfill') 64 | .then(polyfill => { 65 | globalThis.RTCPeerConnection = polyfill.RTCPeerConnection; 66 | return import('node-datachannel'); 67 | }).then(ndc => { 68 | ndc.initLogger('Warning'); // 'Verbose' | 'Debug' | 'Info' | 'Warning' | 'Error' | 'Fatal'; 69 | ndc.preload(); 70 | resolve(); 71 | }); 72 | }); 73 | } 74 | await globalThis.loadingDataChannel; 75 | `; 76 | 77 | function createPlugins(is_node, bundle_all, esm) { 78 | if (is_node && bundle_all) { 79 | throw new Error('Cannot bundle all modules in node'); 80 | } 81 | // plugins for building worker (upload.worker.js) 82 | const workerPlugins = [ 83 | replace({ 84 | include: /\.js$/, 85 | exclude: /node_modules/, 86 | values: { 87 | '_IS_NODE_': is_node.toString(), 88 | '_MULTISYNQ_VERSION_': `"${VERSION}"`, 89 | '_IF_NODE_': (is_node ? '\n' : ''), // uncomment the rest of the line 90 | }, 91 | }), 92 | ]; 93 | // plugins for building client 94 | const plugins = [ 95 | inlineWorkerPlugin({ 96 | // config for building worker 97 | format: 'esm', // only esm appears to work, even in cjs builds 98 | minify: true, 99 | bundle: true, // bundle everything in the worker 100 | platform: is_node ? 'node' : 'browser', 101 | plugins: workerPlugins, 102 | }), 103 | // config for building client 104 | replace({ 105 | include: /\.js$/, 106 | exclude: /node_modules/, 107 | values: { 108 | '_IS_NODE_': is_node.toString(), 109 | '_ENSURE_WEBSOCKET_': (is_node ? `\nimport * as _WS from 'ws';\nglobalThis.WebSocket = _WS.WebSocket;\n` : ''), 110 | '_ENSURE_WORKER_': (is_node ? `\nimport * as _WORKER_THREADS from 'worker_threads';\nglobalThis.Worker = _WORKER_THREADS.Worker;\n` : ''), 111 | '_ENSURE_RTCPEERCONNECTION_': (is_node ? node_webrtc_import : ''), 112 | '_HTML_MODULE_': (is_node ? 'node-html' : 'html'), 113 | '_URLOPTIONS_MODULE_': (is_node ? 'node-urlOptions' : 'urlOptions'), 114 | '_STATS_MODULE_': (is_node ? 'node-stats' : 'stats'), 115 | '_MESSENGER_MODULE_': (is_node ? 'node-messenger' : 'messenger'), 116 | '_MULTISYNQ_VERSION_': `"${VERSION}"`, 117 | }, 118 | }), 119 | ]; 120 | 121 | // by default, all modules are bundled 122 | if (!bundle_all) { 123 | // bundle internal modules but not node_modules 124 | plugins.push(nodeExternalsPlugin({ 125 | allowList: [ 126 | /^crypto-js/, 127 | ], 128 | })); 129 | } 130 | 131 | return plugins; 132 | } 133 | 134 | // build the client in various formats 135 | cleanOutputDirectories([ 136 | 'dist', 137 | 'bundled', 138 | ]).then(() => esbuild.build({ // for browser bundlers 139 | ...COMMON, 140 | format: 'cjs', 141 | outfile: 'dist/multisynq-client.cjs.js', 142 | plugins: createPlugins(false, false, false), 143 | })).then(() => esbuild.build({ 144 | ...COMMON, 145 | format: 'esm', 146 | outfile: 'dist/multisynq-client.esm.js', 147 | plugins: createPlugins(false, false, true), 148 | })).then(() => esbuild.build({ // for node 149 | ...COMMON, 150 | format: 'cjs', 151 | platform: 'node', 152 | outfile: 'dist/multisynq-client-node.cjs', 153 | plugins: createPlugins(true, false, false), 154 | })).then(() => esbuild.build({ 155 | ...COMMON, 156 | format: 'esm', 157 | platform: 'node', 158 | outfile: 'dist/multisynq-client-node.mjs', 159 | plugins: createPlugins(true, false, true), 160 | })).then(() => esbuild.build({ // for CDN (pre-bundled) 161 | ...COMMON, 162 | format: 'iife', 163 | outfile: 'bundled/multisynq-client.min.js', 164 | globalName: 'Multisynq', 165 | plugins: createPlugins(false, true, false), 166 | })).then(() => esbuild.build({ 167 | ...COMMON, 168 | format: 'esm', 169 | outfile: 'bundled/multisynq-client.esm.js', 170 | plugins: createPlugins(false, true, true), 171 | })).then(() => { 172 | generateTypes() 173 | }).catch(error => { 174 | console.error(error); 175 | process.exit(1); 176 | }); 177 | 178 | 179 | function generateTypes() { 180 | // copy the types.d.ts file from client/types.d.ts to dist/multisynq-client.d.ts 181 | const inputFile = path.join('client', 'types.d.ts'); 182 | const outputFile = path.join('dist', 'multisynq-client.d.ts'); 183 | const data = fs.readFileSync(inputFile, 'utf8'); 184 | fs.writeFileSync(outputFile, data, 'utf8'); 185 | } 186 | 187 | async function cleanOutputDirectories(outputDirs) { 188 | for (const dir of outputDirs) { 189 | if (fs.existsSync(dir)) { 190 | fs.rmSync(dir, { recursive: true, force: true }); 191 | } 192 | } 193 | } 194 | 195 | -------------------------------------------------------------------------------- /docs/tutorials/4 View Smoothing/script.js: -------------------------------------------------------------------------------- 1 | // Multisynq Tutorial 4 2 | // View Smoothing 3 | // Croquet Labs (C) 2025 4 | 5 | // -- Constants -- 6 | const Q = Multisynq.Constants; 7 | Q.TICK_MS = 500; // milliseconds per actor tick 8 | Q.SPEED = 0.15; // dot movment speed in pixels per millisecond 9 | Q.CLOSE = 0.1; // minimum distance in pixels to a new destination 10 | Q.SMOOTH = 0.05; // weighting between extrapolated and current positions. 0 > SMOOTH >= 1 11 | 12 | // -- Vector Functions -- 13 | // 14 | // Because these functions don't save any state, they can be safely used by both the model and the view. 15 | 16 | function add(a,b) { 17 | return { x: (a.x + b.x), y: (a.y + b.y) }; 18 | } 19 | 20 | function subtract(a,b) { 21 | return { x: (a.x - b.x), y: (a.y - b.y) }; 22 | } 23 | 24 | function scale(v,s) { 25 | return {x: v.x * s, y: v.y * s}; 26 | } 27 | 28 | function dotProduct(a, b) { 29 | return a.x * b.x + a.y * b.y; 30 | } 31 | 32 | function magnitude(v) { 33 | return Math.sqrt(v.x * v.x + v.y * v.y); 34 | } 35 | 36 | function normalize(v) { 37 | const m = magnitude(v); 38 | return { 39 | x: v.x/m, 40 | y: v.y/m 41 | }; 42 | } 43 | 44 | function lerp(a, b, f = 0.5) { 45 | return { 46 | x: a.x + (b.x - a.x) * f, 47 | y: a.y + (b.y - a.y) * f, 48 | }; 49 | } 50 | 51 | // -- RootModel -- 52 | // 53 | // The root model handles join and exit events. All the real work occurs in the individual actors. 54 | 55 | class RootModel extends Multisynq.Model { 56 | init() { 57 | this.actors = new Map(); 58 | this.actorColors = new Map(); 59 | this.subscribe(this.sessionId, "view-join", this.viewJoin); 60 | this.subscribe(this.sessionId, "view-exit", this.viewDrop); 61 | this.hue = 0; 62 | } 63 | 64 | viewJoin(viewId) { 65 | let actorColor = this.actorColors.get(viewId); 66 | if (!actorColor) { 67 | actorColor = `hsl(${this.hue += 137.5}, 100%, 50%)`; 68 | this.actorColors.set(viewId, actorColor); 69 | } 70 | const actor = Actor.create(viewId); 71 | actor.color = actorColor; 72 | this.actors.set(viewId, actor); 73 | this.publish("actor", "join", actor); 74 | } 75 | 76 | viewDrop(viewId) { 77 | const actor = this.actors.get(viewId); 78 | this.actors.delete(viewId); 79 | actor.destroy(); 80 | this.publish("actor", "exit", actor); 81 | } 82 | } 83 | RootModel.register("RootModel"); 84 | 85 | // -- Actor -- 86 | // 87 | // Each ball is represented by an actor in the model. Every tick the actor moves toward its goal. If 88 | // if receives a 'goto' message from the view, it will change its destination. 89 | 90 | class Actor extends Multisynq.Model { 91 | init(viewId) { 92 | this.viewId = viewId; 93 | this.position = this.randomPosition(); 94 | this.goal = {...this.position}; 95 | this.velocity = {x: 0, y: 0}; 96 | this.future(Q.TICK_MS).tick(); 97 | this.subscribe(viewId, "goto", this.goto); 98 | } 99 | 100 | randomPosition() { 101 | return { x: this.random() * 500, y: this.random() * 500 }; 102 | } 103 | 104 | goto(goal) { 105 | this.goal = goal; 106 | const delta = subtract(goal, this.position); 107 | if (magnitude(delta) < Q.CLOSE) { 108 | this.goto(randomPosition()); 109 | } else { 110 | const unit = normalize(delta); 111 | this.velocity = scale(unit, Q.SPEED); 112 | } 113 | } 114 | 115 | arrived() { 116 | const delta = subtract(this.goal, this.position); 117 | return (dotProduct(this.velocity, delta) <= 0); 118 | } 119 | 120 | tick() { 121 | this.position = add(this.position, scale(this.velocity,Q.TICK_MS)); 122 | if (this.arrived()) this.goto(this.randomPosition()); 123 | this.publish(this.id, "moved", this.now()); 124 | this.future(Q.TICK_MS).tick(); 125 | } 126 | 127 | } 128 | Actor.register("Actor"); 129 | 130 | // -- View Globals -- 131 | 132 | const canvas = document.querySelector("#canvas"); 133 | const cc = canvas.getContext('2d'); 134 | let viewTime = 0; // The last time the view was updated is saved globally so pawns can use it. 135 | 136 | // -- RootView -- 137 | // 138 | // The root view handles clicks and join and exit events. Every update it tells all the pawns 139 | // to draw themselves. 140 | 141 | class RootView extends Multisynq.View { 142 | 143 | constructor(model) { 144 | super(model); 145 | this.pawns = new Map(); 146 | model.actors.forEach(actor => this.addPawn(actor)); 147 | 148 | this.subscribe("actor", "join", this.addPawn); 149 | this.subscribe("actor", "exit", this.removePawn); 150 | 151 | canvas.onclick = e => this.onClick(e); 152 | } 153 | 154 | onClick(e) { 155 | const r = canvas.getBoundingClientRect(); 156 | const scale = canvas.width / Math.min(r.width, r.height); 157 | const x = (e.clientX - r.left) * scale; 158 | const y = (e.clientY - r.top) * scale; 159 | this.publish(this.viewId, "goto", {x,y}); 160 | } 161 | 162 | addPawn(actor) { 163 | const pawn = new Pawn(actor); 164 | this.pawns.set(actor, pawn); 165 | } 166 | 167 | removePawn(actor) { 168 | const pawn = this.pawns.get(actor); 169 | if (!pawn) return; 170 | pawn.detach(); 171 | this.pawns.delete(actor); 172 | } 173 | 174 | update(time) { 175 | // if this is the first update in a while, jump all pawns' times 176 | // so they don't generate huge movement deltas 177 | if (time - viewTime > 1000) { 178 | for (const pawn of this.pawns.values()) pawn.lastMoved = time; 179 | } 180 | // make frame time accessible in event handlers 181 | viewTime = time; 182 | cc.strokeStyle = "black"; 183 | cc.clearRect(0, 0, canvas.width, canvas.height); 184 | cc.strokeRect(0, 0, canvas.width, canvas.height); 185 | for (const pawn of this.pawns.values()) pawn.update(); 186 | } 187 | 188 | } 189 | 190 | // -- Pawn -- 191 | // 192 | // Each actor in the model has corresponding pawn in the view. Pawns update their positions smoothly 193 | // each frame, even if their actor is updating itself much more infrequently. 194 | 195 | class Pawn extends Multisynq.View { 196 | 197 | constructor(actor) { 198 | super(actor); 199 | this.actor = actor; 200 | this.position = {...actor.position}; 201 | this.actorMoved(); 202 | this.subscribe(actor.id, {event: "moved", handling: "oncePerFrame"}, this.actorMoved); 203 | } 204 | 205 | actorMoved() { 206 | // Save when model was last updated 207 | this.lastMoved = viewTime; 208 | } 209 | 210 | update() { 211 | // If this is our pawn, draw our goal and our unsmoothed position from the model. 212 | 213 | if (this.actor.viewId === this.viewId) { 214 | this.draw(this.actor.goal, null, this.actor.color); 215 | this.draw(this.actor.position, "lightgrey"); 216 | } 217 | 218 | // Draw the smoothed positions of all the pawns, including our own. 219 | // First we extrapolate from the last position we received from the model. 220 | // Then we average our extrapolation with our current position. 221 | 222 | const delta = scale(this.actor.velocity, viewTime - this.lastMoved); 223 | const extrapolation = add(this.actor.position, delta); 224 | this.position = lerp(this.position, extrapolation, Q.SMOOTH); 225 | this.draw(this.position, this.actor.color); 226 | } 227 | 228 | draw({x, y}, color, border) { 229 | cc.strokeStyle = border; 230 | cc.fillStyle = color; 231 | cc.beginPath(); 232 | cc.arc(x, y, 10, 0, 2 * Math.PI); 233 | if (color) cc.fill(); 234 | if (border) cc.stroke(); 235 | } 236 | } 237 | 238 | Multisynq.Session.join({ 239 | appId: "io.codepen.multisynq.smooth", 240 | apiKey: "234567_Paste_Your_Own_API_Key_Here_7654321", 241 | name: "public", 242 | password: "none", 243 | model: RootModel, 244 | view: RootView, 245 | tps: 1000/Q.TICK_MS, 246 | }); -------------------------------------------------------------------------------- /client/teatime/src/hashing.js: -------------------------------------------------------------------------------- 1 | import stableStringify from "fast-json-stable-stringify"; 2 | import WordArray from "crypto-js/lib-typedarrays"; 3 | import sha256 from "crypto-js/sha256"; 4 | import urlOptions from "./_URLOPTIONS_MODULE_"; // eslint-disable-line import/no-unresolved 5 | import { App } from "./_HTML_MODULE_"; // eslint-disable-line import/no-unresolved 6 | 7 | const NODE = _IS_NODE_; // replaced by esbuild 8 | 9 | let digest; 10 | if (globalThis.crypto && globalThis.crypto.subtle && typeof globalThis.crypto.subtle.digest === "function") { 11 | digest = globalThis.crypto.subtle.digest.bind(globalThis.crypto.subtle); 12 | } else { 13 | digest = (algorithm, arrayBuffer) => { 14 | if (algorithm !== "SHA-256") throw Error(`${App.libName}: only SHA-256 available`); 15 | const inputWordArray = WordArray.create(arrayBuffer); 16 | const outputWordArray = sha256(inputWordArray); 17 | const bytes = cryptoJsWordArrayToUint8Array(outputWordArray); 18 | return bytes.buffer; 19 | }; 20 | } 21 | 22 | export function cryptoJsWordArrayToUint8Array(wordArray) { 23 | const l = wordArray.sigBytes; 24 | const words = wordArray.words; 25 | const result = new Uint8Array(l); 26 | let i = 0, j = 0; 27 | while (i < l) { 28 | const w = words[j++]; 29 | result[i++] = (w & 0xff000000) >>> 24; if (i === l) break; 30 | result[i++] = (w & 0x00ff0000) >>> 16; if (i === l) break; 31 | result[i++] = (w & 0x0000ff00) >>> 8; if (i === l) break; 32 | result[i++] = (w & 0x000000ff); 33 | } 34 | return result; 35 | } 36 | 37 | function funcSrc(func) { 38 | // this is used to provide the source code for hashing, and hence for generating 39 | // a session ID. we do some minimal cleanup to unify the class / function strings 40 | // as provided by different browsers. 41 | function cleanup(str) { 42 | const openingBrace = str.indexOf('{'); 43 | const closingBrace = str.lastIndexOf('}'); 44 | if (openingBrace === -1 || closingBrace === -1 || closingBrace < openingBrace) return str; 45 | const head = str.slice(0, openingBrace).replace(/\s+/g, ' ').replace(/\s\(/, '('); 46 | const body = str.slice(openingBrace + 1, closingBrace); 47 | return `${head.trim()}{${body.trim()}}`; 48 | } 49 | let src = cleanup("" + func); 50 | if (!src.startsWith("class")) { 51 | // possibly class has been minified and replaced with function definition 52 | // add source of prototype methods 53 | const p = func.prototype; 54 | if (p) src += Object.getOwnPropertyNames(p).map(n => `${n}:${cleanup("" + p[n])}`).join(''); 55 | } 56 | return src; 57 | // remnants of an experiment (june 2019) in deriving the same hash for code 58 | // that is semantically equivalent, even if formatted differently - so that 59 | // tools such as Codepen, which mess with white space depending on the 60 | // requested view type (e.g., debug or not), would nonetheless generate 61 | // the same session ID for all views. 62 | // our white-space standardisation involved stripping space immediately 63 | // inside a brace, and at the start of each line: 64 | 65 | // .replace(/\{\s+/g, '{').replace(/\s+\}/g, '}').replace(/^\s+/gm, '')}}`; 66 | 67 | // upon realising that Codepen also reserves the right to inject code, such 68 | // as into "for" loops to allow interruption, we decided to abandon this 69 | // approach. users should just get used to different views having different 70 | // session IDs. 71 | } 72 | 73 | export function fromBase64url(base64) { 74 | return new Uint8Array(atob(base64.padEnd((base64.length + 3) & ~3, "=") 75 | .replace(/-/g, "+") 76 | .replace(/_/g, "/")).split('').map(c => c.charCodeAt(0))); 77 | } 78 | 79 | export function toBase64url(bits) { 80 | return btoa(String.fromCharCode(...new Uint8Array(bits))) 81 | .replace(/=/g, "") 82 | .replace(/\+/g, "-") 83 | .replace(/\//g, "_"); 84 | } 85 | 86 | /** return buffer hashed into 256 bits encoded using base64 (suitable in URL) */ 87 | export async function hashBuffer(buffer) { 88 | // MS Edge does not like empty buffer 89 | if (buffer.length === 0) return "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU"; 90 | const bits = await digest("SHA-256", buffer); 91 | return toBase64url(bits); 92 | } 93 | 94 | function debugHashing() { return urlOptions.has("debug", "hashing", false); } 95 | 96 | let debugHashes = {}; 97 | 98 | const encoder = new TextEncoder(); 99 | 100 | /** return string hashed into 256 bits encoded using base64 (suitable in URL) */ 101 | export async function hashString(string) { 102 | const buffer = encoder.encode(string); 103 | const hash = await hashBuffer(buffer); 104 | debugHashes[hash] = {string, buffer}; 105 | return hash; 106 | } 107 | 108 | const hashPromises = []; 109 | const codeHashCache = {}; // persistentID to { codeHashes, computedCodeHash }, cached on first JOIN in case additional code or constants (presumably for a different session) get registered later, and the user explicitly leaves and re-joins 110 | 111 | export function addClassHash(cls, classId) { 112 | const source = funcSrc(cls); 113 | const hashPromise = hashString(`${classId}:${source}`); 114 | hashPromises.push(hashPromise); 115 | hashPromise.then(hash => debugHashes[hash].what = `Class ${classId}`); 116 | } 117 | 118 | export function addConstantsHash(constants) { 119 | // replace functions with their source 120 | const json = JSON.stringify(constants, (_, val) => typeof val === "function" ? funcSrc(val) : val); 121 | if (json === "{}") return; 122 | // use a stable stringification 123 | const obj = JSON.parse(json); 124 | const string = stableStringify(obj); 125 | const hashPromise = hashString(string); 126 | hashPromises.push(hashPromise); 127 | hashPromise.then(hash => debugHashes[hash].what = `${App.libName} Constants`); 128 | } 129 | 130 | /** generate persistentId for the vm */ 131 | export async function hashNameAndOptions(appIdAndName, options) { 132 | return hashString(appIdAndName + stableStringify(options)); 133 | } 134 | 135 | const logged = new Set(); 136 | 137 | export async function hashSessionAndCode(persistentId, developerId, params, hashOverride, sdk_version) { 138 | // codeHashes are from registered user models and constants (in hashPromises). 139 | // jul 2021: note that if multiple sessions are loaded in the same tab, *all* 140 | // sessions' models and constants registered up to this point will be taken into 141 | // account. later we'd like to provide an interface (perhaps through App) for 142 | // registering each session's resources separately. 143 | let codeHashes; 144 | /** identifies the code being executed - user code, constants, multisynq */ 145 | let computedCodeHash; 146 | const cached = codeHashCache[persistentId]; 147 | let cacheAnnotation = ""; 148 | if (cached) { 149 | // the cached codeHashes list is only used in logging, and logging will 150 | // only happen if the final derived session ID has changed. 151 | codeHashes = cached.codeHashes; 152 | computedCodeHash = cached.computedCodeHash; 153 | cacheAnnotation = " (code hashing from cache)"; 154 | } else { 155 | codeHashes = await Promise.all(hashPromises); 156 | computedCodeHash = await hashString([sdk_version, ...codeHashes].join('|')); 157 | codeHashCache[persistentId] = { codeHashes, computedCodeHash }; 158 | } 159 | // let developer override hashing (at their own peril) 160 | const effectiveCodeHash = hashOverride || computedCodeHash; 161 | /** identifies the session */ 162 | const id = await hashString(persistentId + '|' + developerId + stableStringify(params) + effectiveCodeHash); 163 | // log all hashes if debug=hashing 164 | if (debugHashing() && !logged.has(id)) { 165 | const charset = NODE ? 'utf-8' : [...document.getElementsByTagName('meta')].find(el => el.getAttribute('charset')); 166 | if (!charset) console.warn(`${App.libName}: Missing declaration. ${App.libName} model code hashing might differ between browsers.`); 167 | debugHashes[computedCodeHash].what = "Version ID"; 168 | debugHashes[persistentId].what = "Persistent ID"; 169 | debugHashes[id].what = "Session ID"; 170 | if (effectiveCodeHash !== computedCodeHash) { 171 | codeHashes.push(computedCodeHash); // for allHashes 172 | debugHashes[computedCodeHash].what = "Computed Version ID (replaced by overrideHash)"; 173 | debugHashes[effectiveCodeHash] = { what: "Version ID (as specified by overrideHash)"}; 174 | } 175 | const allHashes = [...codeHashes, effectiveCodeHash, persistentId, id].map(each => ({ hash: each, ...debugHashes[each]})); 176 | console.log(`${App.libName}: Debug Hashing for session ${id}${cacheAnnotation}`, allHashes); 177 | logged.add(id); 178 | } 179 | if (!debugHashing()) debugHashes = {}; // clear debugHashes to save memory 180 | return { id, persistentId, codeHash: effectiveCodeHash, computedCodeHash }; 181 | } 182 | -------------------------------------------------------------------------------- /docs/tutorials/2_9_data.md: -------------------------------------------------------------------------------- 1 | Copyright © 2025 Croquet Labs 2 | 3 | Multisynq offers secure bulk data storage service for apps. A Multisynq application can upload a file, typically media content or a document file, to the Multisynq file server. The `store()` function returns a *data handle* that can be sent to replicated models in a Multisynq message, and then other participants can `fetch()` the stored data. Off-loading the actual bits of data to a file server and keeping only its meta data in the model is a lot more efficient than trying to send that data via `publish`/`subscribe`. It also allows caching. 4 | 5 | Just like snapshots and persistent data, data uploaded via the Data API is end-to-end encrypted with the session password. That means it can only be decoded from within the session. 6 | 7 | Optionally, you can create a *shareable handle* where each data is encrypted individually with a random key, which becomes part of the data handle. 8 | Its string form can be shared between sessions and even apps. If you keep this kind of handle stored in the model it is protected by the general end-to-end encryption of the session. 9 | If it leaks, however, anyone will be able to access and decrypt that data, unlike with the default, non-shareable handle. 10 | 11 | Following is a full example of the Data API. 12 | 13 | ~~~~ HTML 14 | 15 | 16 | 17 | Data + Persistence Example 18 | 19 | 20 | 21 | 22 | click to import picture, or drag-and-drop one 23 | 129 | 130 | 131 | ~~~~ 132 | 133 | When a user drops an image file onto the browser window, or clicks in the window to get the file dialog and chooses a file, the `addFile()` of the `DataTestView` is invoked. It calls [data.store()]{@link Data#store} with `data` as an `ArrayBuffer`. [data.store()]{@link Data#store} returns asynchronously the data handle, then an `"add-asset"` event with the handle is published and the handle gets stored in the model by the `addAsset()` event handler. In addition to the handle, this example also stores some meta data, like file name, MIME type, and file size. 134 | 135 | In `addAsset()`, the model also publishes an `"asset-added"` event for all views. The views fetch the data from the file server by calling [data.fetch()]{@link Data#fetch}. Then they create a `Blob` object and use it as the `background-image` CSS style. Now the views of every user show the first user's image. 136 | 137 | By default, [data.store()]{@link Data#store} does not preserve the `ArrayBuffer` data, it is detached when it is transferred to the WebWorker that handles encrypting and uploading data (see [ArrayBuffer]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#transferring_arraybuffers} and [Transferable objects]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects}). This is done for efficiency, and the reason why in this example we put the file's size into a variable beforehand (after storing it would be `0`). If you need to use the same data after you call [data.store()]{@link Data#store}, pass `{keep: true}` in the store options, which will transfer a copy instead. 138 | 139 | To be able to access the uploaded data even when the app code changes, the data handle needs to be [persisted]{@link Model#persistSession}, so the data handle can be recreated in a new session with the same `appId` and session `name` but modified code (see [Persistence]{@tutorial 2_A_persistence} tutorial). Since persistence needs JSON data, we use [Data.toId()]{@link Data.toId} to create a string representation of the handle, and recreate the equivalent data handle by calling [Data.fromId()]{@link Data.fromId}. 140 | 141 | # Best Practices 142 | Keep in mind that accessing external services is responsibility of the view, as the model should be concerned with the logical data. Calling [data.store()]{@link Data#store} and [data.fetch()]{@link Data#fetch} is done by the view asynchronously, and the view notifies the model via a Multisynq message. 143 | 144 | You will most likely to store the `id` for the data handle created by [data.toId()]{@link Data.toId} for persistent data. It is indeed fine to store the id in the model as the primary data, and the view creates the data handle from it by calling [data.fromId()]{@link Data.fromId} before fetching data. 145 | 146 | As in the example above, you can use an `input` DOM element with `type="file"` to get the browser's file dialog or camera roll dialog. However, while the dialog is opened, on some systems (like iOS) the JavaScript execution is suspended and the Multisynq network connection may disconnect while the user takes a long time to select a file or take a photo. We handle this case by storing the information of the chosen file in a global variable, and upload it when the view gets constructed again. 147 | 148 | Notice that `init()` of the view calls `assetAdded` when there already is `model.asset` so that a view that joined later shows the same image. This is a common pattern that is not limited to apps that uses Data API, but in general Multisynq views should be initialized to reflect the current model state when constructed, without relying on events. -------------------------------------------------------------------------------- /docs/tutorials/1_2_simple_animation.md: -------------------------------------------------------------------------------- 1 | Copyright © 2025 Croquet Labs 2 | 3 | This tutorial will teach you how to create multi-user shared animations and interactions. If you click one of the bouncing objects it will stop moving. Click again and it will start bouncing again. This tutorial isn't really that much more complex than the Hello World application. It just has a few more moving parts and really demonstrates how the model is used to compute a simulation and how the view is used to display it and interact with it. 4 | 5 |

6 | See the Pen 7 | Simple Animation by Multisynq (@multisynq) 8 | on CodePen. 9 |

10 | 11 | 12 | 13 | ## **Try it out!** 14 | The first thing to do is click or scan the QR code above. This will launch a new Codepen instance of this session. If you compare the two sessions, you will see that the animated simulations are identical. The balls all move and bounce exactly the same. You can stop and start any ball by clicking on it, which will start or stop it in every session. You can't stop the rounded rectangle - it is just like a regular ball but ignores user actions. Any reader of this documentation can start or stop the balls while they are animating. You may notice that this is happening. It just means there is someone else out there working with the tutorial at the same time as you. 15 | 16 | There are three things we will learn here. 17 | 18 | 1. Creating a simulation model. 19 | 2. Creating an interactive view. 20 | 3. How to safely communicate between them. 21 | 22 | 23 | ## Simple Animation Model 24 | 25 | Our application uses two Multisynq Model subclasses, MyModel and BallModel. Both these classes need to be registered with Multisynq. 26 | 27 | In addition, this app makes use of [Multisynq.Constants]{@link Constants}. 28 | Although models must not use global variables, global constants are fine. 29 | To ensure that all users in a session use the same value of these constants, add them to the Multisynq.Constants object. 30 | Multisynq.Constants is recursively frozen once a session has started, to avoid accidental modification. 31 | Here we assign Multisynq.Constants into the variable Q as a shorthand. 32 | 33 | ``` 34 | const Q = Multisynq.Constants; 35 | Q.BALL_NUM = 25; // how many balls do we want? 36 | Q.STEP_MS = 1000 / 30; // bouncing ball tick interval in ms 37 | Q.SPEED = 10; // max speed on a dimension, in units/s 38 | ``` 39 | 40 | MyModel is the root model, and is therefore what will be passed into [Multisynq.Session.join]{@link Session.join}. 41 | In this app, MyModel also creates and stores the BallModel objects, holding them in the array MyModel.children. 42 | 43 | A BallModel is the model for a shaped, colored, bouncing ball. The model itself has no direct say in the HTML that will be used to display the ball. For the shape, for example, the model records just a string - either `'circle'` or `'roundRect'` - that the view will use to generate a visual element that (by the workings of the app's CSS) will be displayed as the appropriate shape. The BallModel also initializes itself with a random color, position, and speed vector. 44 | 45 | ```this.subscribe(this.id, 'touch-me', this.startStop);``` 46 | 47 | The BallModel [subscribes]{@link Model#subscribe} to the `'touch-me'` event, to which it will respond by stopping or restarting its motion. Each BallModel object individually subscribes to this event type, but only for events that are published using the BallModel's own ID as scope. Each ball's dedicated BallView object keeps a record of its model's ID, for use when publishing the `'touch-me'` events in response to user touches. 48 | 49 | ```this.future(Q.STEP_MS).step();``` 50 | 51 | Having completed its initialization, the BallModel [schedules]{@link Model#future} the first invocation of its own `step()` method. This is the same pattern as seen in the previous tutorial; `step()` will continue the stepping by re-scheduling itself each time. 52 | 53 | Worth noting here is that the step invocation applies just to one ball, with each BallModel taking care of its own update tick. That may seem like a lot of future messages for the system to handle (25 balls ticking at 30Hz will generate 750 messages per second) - but future messages are very efficient, involving little overhead beyond the basic method invocation. 54 | 55 | ``` 56 | BallModel.step() { 57 | if (this.alive) this.moveBounce(); 58 | this.future(Q.STEP_MS).step(); 59 | } 60 | ``` 61 | 62 | If the `alive` flag is set, the `step()` function will call `moveBounce()`. In any case, `step()` schedules the next step, the appropriate number of milliseconds in the future. 63 | 64 | ``` 65 | BallModel.moveBounce() { 66 | const [x, y] = this.pos; 67 | if (x<=0 || x>=1000 || y<=0 || y>=1000) 68 | this.speed = this.randomSpeed(); 69 | this.moveTo([x + this.speed[0], y + this.speed[1]]); 70 | } 71 | ``` 72 | 73 | `BallModel.moveBounce()` has the job of updating the position of a ball object, including bouncing off container walls when necessary. It embodies a simple strategy: if the ball is found to be outside the container bounds, `moveBounce()` replaces the ball's speed with a new speed vector `BallModel.randomSpeed()`. Because the new speed is random, it might turn out to take the ball a little further out of bounds - but in that case the ball will just try again, with another random speed, on the next `moveBounce`. 74 | 75 | ``` 76 | randomSpeed() { 77 | const xs = this.random() * 2 - 1; 78 | const ys = this.random() * 2 - 1; 79 | const speedScale = Q.SPEED / (Math.sqrt(xs*xs + ys*ys)); 80 | return [xs * speedScale, ys * speedScale]; 81 | } 82 | ``` 83 | 84 | The generation of new speed vectors is an example of our use of a replicated random-number generator. Every instance of this session will compute exactly the same sequence of random numbers. Therefore, when a ball bounces, every instance will come up with exactly the same new speed. 85 | 86 | ## Simple Animation View 87 | 88 | Like the Model, the View in this app comprises two classes: MyView and BallView. 89 | 90 | ### MyView 91 | 92 | MyView.constructor(model) will be called when an app session instance starts up. It is passed the MyModel object as an argument. The constructor's job is to build the visual representation of the model for this instance of the session. The root of that representation, in this app, is a "div" element that will serve as the balls' container. 93 | 94 | ```model.children.forEach(child => this.attachChild(child));``` 95 | 96 | The MyModel has children - the BallModel objects - for which MyView must also create a visual representation. It does so by accessing the model's children collection and creating a new view object for each child. 97 | 98 | Note that although it is fine for the view to access the model directly here to read its state - in this case, the children - the view **MUST NOT** modify the model (or its child models) in any way. 99 | 100 | ``` 101 | MyView.attachChild(child) { 102 | this.element.appendChild(new BallView(child).element); 103 | } 104 | ``` 105 | 106 | For each child BallModel a new BallView object is created. The BallView creates a document element to serve as the visual representation of the bouncing ball; the MyView object adds the element for each BallView as a child of its own element, the containing div. 107 | 108 | MyView also listens for "resize" events from the browser, and uses them to set a suitable size for the view by setting its scale (which also sets the scale for the children - i.e., the balls). When there are multiple users watching multiple instances of this app on browser windows of different sizes, the rescaling ensures that everyone still sees the same overall scene. 109 | 110 | ``` 111 | MyView.detach() { 112 | super.detach(); 113 | let child; 114 | while (child = this.element.firstChild) this.element.removeChild(child); 115 | } 116 | ``` 117 | 118 | When a session instance is shut down (including the reversible shutdown that happens if a tab is hidden for ten seconds or more), its root view is destroyed. If the instance is re-started, a completely new root view will be built. Therefore, on shutdown, the root view is sent `detach` to give it the chance to clean up its resources. MyView handles this by destroying all the child views that it has added to the `"animation"` `div` element during this session. 119 | 120 | ### BallView 121 | 122 | The BallView tracks the associated BallModel. 123 | 124 | BallView constructs a document element based on the type and color properties held by the BallModel, and sets the element's initial position using the model's pos property. 125 | 126 | ```this.subscribe(model.id, { event: 'pos-changed', handling: "oncePerFrame" }, this.move);``` 127 | 128 | The BallView subscribes to the 'pos-changed' event, which the BallModel publishes each time it updates the ball position. Like the 'touch-me' event, these events are sent in the scope of the individual BallModel's ID. No other ball's model or view will pay any attention to the events, which makes their distribution highly efficient. As a further efficiency consideration, the `handling: "oncePerFrame"` flag is used to ensure that even if multiple events for a given ball arrive within the same rendering frame, only one (the latest) will be passed to the subscribed handler. 129 | 130 | ```this.enableTouch();``` 131 | 132 | ``` 133 | BallView.enableTouch() { 134 | const el = this.element; 135 | if (TOUCH) el.ontouchstart = start => { 136 | start.preventDefault(); 137 | this.publish(el.id, 'touch-me'); 138 | }; else el.onmousedown = start => { 139 | start.preventDefault(); 140 | this.publish(el.id, 'touch-me'); 141 | }; 142 | } 143 | ``` 144 | BallView.enableTouch sets up the BallView element to publish a 'touch-me' event when the element is clicked on. 145 | The BallModel subscribes to the 'touch-me' event and toggles the ball motion on and off. 146 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2019-2025 Croquet Labs 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /docs/tutorials/5 3D Animation/script.js: -------------------------------------------------------------------------------- 1 | // Multisynq Tutorial 5 2 | // 3D Animation Demo 3 | // Croquet Labs (C) 2025 4 | 5 | const Q = Multisynq.Constants; 6 | // Pseudo-globals 7 | Q.NUM_BALLS = 12; // number of bouncing balls 8 | Q.BALL_RADIUS = 0.25; 9 | Q.CENTER_SPHERE_RADIUS = 1.5; // a large sphere to bounce off 10 | Q.CENTER_SPHERE_NEUTRAL = 0xaaaaaa; // color of sphere before any bounces 11 | Q.CONTAINER_SIZE = 4; // edge length of invisible containing cube 12 | Q.STEP_MS = 1000 / 20; // step time in ms 13 | Q.SPEED = 1.5; // max speed on a dimension, in units/s 14 | 15 | class MyModel extends Multisynq.Model { 16 | 17 | init(options) { 18 | // force init 14 19 | super.init(options); 20 | this.centerSphereRadius = Q.CENTER_SPHERE_RADIUS; 21 | this.centerSpherePos = [0, 0, -Q.CONTAINER_SIZE/2]; // embedded half-way into the back wall 22 | this.children = []; 23 | for (let i = 0; i < Q.NUM_BALLS; i++) this.children.push(BallModel.create({ sceneModel: this })); 24 | this.subscribe(this.id, 'sphere-drag', this.centerSphereDragged); // someone is dragging the center sphere 25 | this.subscribe(this.id, 'reset', this.resetCenterSphere); // someone has clicked the center sphere 26 | } 27 | 28 | centerSphereDragged(pos) { 29 | this.centerSpherePos = pos; 30 | this.publish(this.id, 'sphere-pos-changed', pos); 31 | } 32 | 33 | resetCenterSphere() { 34 | this.publish(this.id, 'recolor-center-sphere', Q.CENTER_SPHERE_NEUTRAL); 35 | } 36 | } 37 | 38 | MyModel.register("MyModel"); 39 | 40 | class BallModel extends Multisynq.Model { 41 | 42 | init(options={}) { 43 | super.init(); 44 | this.sceneModel = options.sceneModel; 45 | 46 | const rand = range => Math.floor(range * Math.random()); // integer random less than range 47 | this.radius = Q.BALL_RADIUS; 48 | this.color = `hsl(${rand(360)},${rand(50)+50}%,50%)`; 49 | this.resetPosAndSpeed(); 50 | 51 | this.subscribe(this.sceneModel.id, 'reset', this.resetPosAndSpeed); // the reset event will be sent using the model id as scope 52 | 53 | this.future(Q.STEP_MS).step(); 54 | } 55 | 56 | // a ball resets itself by positioning at the center of the center-sphere 57 | // and giving itself a randomized velocity 58 | resetPosAndSpeed() { 59 | const srand = range => range * 2 * (Math.random() - 0.5); // float random between -range and +range 60 | this.pos = this.sceneModel.centerSpherePos.slice(); 61 | const speedRange = Q.SPEED * Q.STEP_MS / 1000; // max speed per step 62 | this.speed = [ srand(speedRange), srand(speedRange), srand(speedRange) ]; 63 | } 64 | 65 | step() { 66 | this.moveBounce(); 67 | this.future(Q.STEP_MS).step(); // arrange to step again 68 | } 69 | 70 | moveBounce() { 71 | this.bounceOffContainer(); 72 | this.bounceOffCenterSphere(); 73 | const pos = this.pos; 74 | const speed = this.speed; 75 | this.moveTo([ pos[0] + speed[0], pos[1] + speed[1], pos[2] + speed[2] ]); 76 | } 77 | 78 | bounceOffCenterSphere() { 79 | const pos = this.pos; 80 | const spherePos = this.sceneModel.centerSpherePos; // a model is allowed to read state of another model 81 | const distFromCenter = posArray => { 82 | let sq = 0; 83 | posArray.forEach((p, i) => { 84 | const diff = spherePos[i] - p; 85 | sq += diff * diff; 86 | }); 87 | return Math.sqrt(sq); 88 | }; 89 | const speed = this.speed; 90 | const threshold = Q.CENTER_SPHERE_RADIUS + this.radius; 91 | const distBefore = distFromCenter(pos); 92 | const distAfter = distFromCenter([ pos[0] + speed[0], pos[1] + speed[1], pos[2] + speed[2] ]); 93 | if (distBefore >= threshold && distAfter < threshold) { 94 | const unitToCenter = pos.map((p, i) => (spherePos[i] - p)/distBefore); 95 | const speedAcrossBoundary = speed[0] * unitToCenter[0] + speed[1] * unitToCenter[1] + speed[2] * unitToCenter[2]; 96 | this.speed = this.speed.map((v, i) => v - 2 * speedAcrossBoundary * unitToCenter[i]); 97 | this.publish(this.sceneModel.id, 'recolor-center-sphere', this.color); 98 | } 99 | } 100 | 101 | bounceOffContainer() { 102 | const pos = this.pos; 103 | const speed = this.speed; 104 | pos.forEach((p, i) => { 105 | if (Math.abs(p) > Q.CONTAINER_SIZE/2 - this.radius) speed[i] = Math.abs(speed[i]) * -Math.sign(p); 106 | }); 107 | } 108 | 109 | // the ball moves by recording its new position, then publishing that 110 | // position in an event that its view is expected to have subscribed to 111 | moveTo(pos) { 112 | this.pos = pos; 113 | this.publish(this.id, 'pos-changed', this.pos); 114 | } 115 | } 116 | 117 | BallModel.register("BallModel"); 118 | 119 | // one-time function to set up Three.js, with a simple lit scene 120 | function setUpScene() { 121 | const scene = new THREE.Scene(); 122 | scene.add(new THREE.AmbientLight(0xffffff, 0.5)); 123 | const light = new THREE.PointLight(0xffffff, 1); 124 | light.position.set(50, 50, 50); 125 | scene.add(light); 126 | 127 | const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 10000); 128 | camera.position.set(0, 0, 4); 129 | const threeCanvas = document.getElementById("three"); 130 | const renderer = new THREE.WebGLRenderer({ canvas: threeCanvas }); 131 | renderer.setClearColor(0xaa4444); 132 | 133 | function onWindowResize() { 134 | camera.aspect = window.innerWidth / window.innerHeight; 135 | camera.updateProjectionMatrix(); 136 | renderer.setSize(window.innerWidth, window.innerHeight); 137 | } 138 | window.addEventListener('resize', onWindowResize, false); 139 | onWindowResize(); 140 | 141 | // utility objects for managing pointer interaction 142 | const raycaster = new THREE.Raycaster(); 143 | let dragObject = null; 144 | let dragged; 145 | const dragOffset = new THREE.Vector3(); 146 | const dragPlane = new THREE.Plane(); 147 | const mouse = new THREE.Vector2(); 148 | const THROTTLE_MS = 1000 / 20; // minimum delay between pointer-move events that we'll handle 149 | let lastTime = 0; 150 | function setMouse(event) { 151 | mouse.x = (event.clientX / window.innerWidth) * 2 - 1; 152 | mouse.y = -(event.clientY / window.innerHeight) * 2 + 1; 153 | } 154 | 155 | function onPointerDown(event) { 156 | event.preventDefault(); 157 | setMouse(event); // convert from window coords to relative (-1 to +1 on each of x, y) 158 | raycaster.setFromCamera(mouse, camera); 159 | const intersects = raycaster.intersectObjects(scene.children); 160 | for (let i = 0; i < intersects.length && !dragObject; i++) { 161 | const intersect = intersects[i]; 162 | const threeObj = intersect.object; 163 | if (threeObj.q_draggable) { // a flag that we set on just the central sphere 164 | dragObject = threeObj; 165 | dragged = false; // so we can detect a non-dragging click 166 | dragOffset.subVectors(dragObject.position, intersect.point); // position relative to pointer 167 | // set up for drag in vertical plane perpendicular to camera direction 168 | dragPlane.setFromNormalAndCoplanarPoint(camera.getWorldDirection(new THREE.Vector3()), intersect.point); 169 | } 170 | } 171 | } 172 | threeCanvas.addEventListener('pointerdown', onPointerDown); 173 | 174 | function onPointerMove(event) { 175 | event.preventDefault(); 176 | 177 | // ignore if there is no drag happening 178 | if (!dragObject) return; 179 | 180 | // ignore if the event is too soon after the last one 181 | if (event.timeStamp - lastTime < THROTTLE_MS) return; 182 | lastTime = event.timeStamp; 183 | 184 | const lastMouse = {...mouse}; 185 | setMouse(event); 186 | // ignore if the event is too close on the screen to the last one 187 | if (Math.abs(mouse.x-lastMouse.x) < 0.01 && Math.abs(mouse.y - lastMouse.y) < 0.01) return; 188 | 189 | raycaster.setFromCamera(mouse, camera); 190 | const dragPoint = raycaster.ray.intersectPlane(dragPlane, new THREE.Vector3()); 191 | dragObject.q_onDrag(new THREE.Vector3().addVectors(dragPoint, dragOffset)); 192 | dragged = true; // a drag has happened (so don't treat the pointerup as a click) 193 | } 194 | threeCanvas.addEventListener('pointermove', onPointerMove); 195 | 196 | function onPointerUp(event) { 197 | event.preventDefault(); 198 | if (dragObject) { 199 | if (!dragged && dragObject.q_onClick) dragObject.q_onClick(); 200 | dragObject = null; 201 | } 202 | } 203 | threeCanvas.addEventListener('pointerup', onPointerUp); 204 | 205 | // function that the app must invoke when ready to render the scene 206 | // on each animation frame. 207 | function sceneRender() { renderer.render(scene, camera); } 208 | 209 | return { scene, sceneRender }; 210 | } 211 | 212 | class MyView extends Multisynq.View { 213 | 214 | constructor(model) { 215 | super(model); 216 | this.sceneModel = model; 217 | const sceneSpec = setUpScene(); // { scene, sceneRender } 218 | this.scene = sceneSpec.scene; 219 | this.sceneRender = sceneSpec.sceneRender; 220 | this.centerSphere = new THREE.Mesh( 221 | new THREE.SphereGeometry(model.centerSphereRadius, 16, 16), 222 | new THREE.MeshStandardMaterial({ color: Q.CENTER_SPHERE_NEUTRAL, roughness: 0.7 })); 223 | this.centerSphere.position.fromArray(model.centerSpherePos); 224 | this.scene.add(this.centerSphere); 225 | // set Multisynq app-specific properties for handling events 226 | this.centerSphere.q_onClick = () => this.publish(model.id, 'reset'); 227 | this.centerSphere.q_draggable = true; 228 | this.centerSphere.q_onDrag = posVector => this.posFromSphereDrag(posVector.toArray()); 229 | this.subscribe(model.id, 'sphere-pos-changed', this.moveSphere); 230 | this.subscribe(model.id, 'recolor-center-sphere', this.recolorSphere); 231 | model.children.forEach(childModel => this.attachChild(childModel)); 232 | } 233 | 234 | posFromSphereDrag(pos) { 235 | const limit = Q.CONTAINER_SIZE / 2; 236 | // constrain x and y to container (z isn't expected to be changing) 237 | [0, 1].forEach(i => { if (Math.abs(pos[i]) > limit) pos[i] = limit * Math.sign(pos[i]); }); 238 | this.publish(this.sceneModel.id, 'sphere-drag', pos); 239 | } 240 | 241 | moveSphere(pos) { 242 | // this method just moves the view of the sphere 243 | this.centerSphere.position.fromArray(pos); 244 | } 245 | 246 | recolorSphere(color) { 247 | this.centerSphere.material.color.copy(new THREE.Color(color)); 248 | } 249 | 250 | attachChild(childModel) { 251 | this.scene.add(new BallView(childModel).object3D); 252 | } 253 | 254 | update(time) { 255 | this.sceneRender(); 256 | } 257 | } 258 | 259 | class BallView extends Multisynq.View { 260 | 261 | constructor(model) { 262 | super(model); 263 | this.object3D = new THREE.Mesh( 264 | new THREE.SphereGeometry(model.radius, 12, 12), 265 | new THREE.MeshStandardMaterial({ color: model.color }) 266 | ); 267 | this.move(model.pos); 268 | this.subscribe(model.id, { event: 'pos-changed', handling: 'oncePerFrame' }, this.move); 269 | } 270 | 271 | move(pos) { 272 | this.object3D.position.fromArray(pos); 273 | } 274 | } 275 | 276 | Multisynq.Session.join({ 277 | appId: "io.codepen.multisynq.threed_anim", 278 | apiKey: "234567_Paste_Your_Own_API_Key_Here_7654321", 279 | name: "public", 280 | password: "none", 281 | model: MyModel, 282 | view: MyView, 283 | }); --------------------------------------------------------------------------------

Vite + TypeScript + Multisynq