Script overte

source/script/assignment-client-scripts.rst

@@ -0,0 +1,67 @@
+#########################
+Assignment Client Scripts
+#########################
+
+Assignment Client (AC) scripts (also known as "persistent scripts") run persistently in a domain and aren't affected by other scripts. These scripts run on an assignment client separate from the Interface, so the script will continue to run until you either remove the script from the domain or you shut down the domain entirely.
+
+With AC scripts, you can do things like coordinate actions between entities and avatars, and add virtual pets to greet visitors to your domain.
+
+.. contents:: On This Page
+    :depth: 2
+
+----------------
+Add an AC Script
+----------------
+
+Once you've written and hosted your script, you need to add it to a domain, either your own or one where you have permissions to run an AC script.
+
+1. Open your 'Domain Administration Panel'. If you are on a local domain server, open it by clicking on the Overte icon in the taskbar notifications and 'click Settings'.
+2. From the menu, go to **Content > Scripts**.
+3. In the Persistent Scripts section, click **+** and paste the URL to your script under 'Script URL'. 
+
+.. image:: _images/ac-script.png
+
+4. At the top of the page, click 'Save and Restart'. Now, every time you enter that domain, the AC script will be running.
+
+-----------------------
+Example of an AC Script
+-----------------------
+
+The following script counts the number of entities found in a domain using Overte's `EntityViewer <https://apidocs.overte.org/EntityViewer.html>`_.
+
+.. code-block:: javascript
+
+    "use strict"
+    const SEARCH_CENTER = {x: 0, y: -10, z: 0};
+    const SEARCH_RADIUS = 100;
+
+    let isInitialized = false;
+    const timeout = 1000;
+
+    const update = function(deltaTime) {
+        if (!isInitialized) {
+            if (Entities.serversExist() && Entities.canRez()) {
+                EntityViewer.setPosition(SEARCH_CENTER);
+                EntityViewer.setCenterRadius(SEARCH_RADIUS);
+                EntityViewer.queryOctree();
+
+                Script.setTimeout(function(){
+                    var foundEntities = Entities.findEntities(SEARCH_CENTER, SEARCH_RADIUS).length;
+
+                    print("AC Script found: " + foundEntities + " entities within " + SEARCH_RADIUS + "m of " + JSON.stringify(SEARCH_CENTER));
+
+                }, timeout);
+
+                isInitialized = true;
+                Script.update.disconnect(update);
+            }
+        }
+    };
+
+    Script.update.connect(update);
+
+**See Also**
+
+- `Configure Your Domain Settings <../host/configure-settings>`_
+- `Get Started with Scripting <get-started-with-scripting>`_
+- `Write Your Own Scripts <write-scripts>`_

source/script/avatar-scripts.rst

@@ -0,0 +1,119 @@
+##############
+Avatar Scripts
+##############
+
+Avatar scripts are bound to an avatar. This means that they run when a user puts on a specific avatar. Likewise, avatar scripts stop running when the avatar is removed or changed. Other users in the domain will be able to see the script in action, but they will not be able to run the script themselves.
+
+With avatar scripts, you can do things like make your hair flow or create particle clouds around your avatar.
+
+.. contents:: On This Page
+    :depth: 2
+
+--------------------
+Add an Avatar Script
+--------------------
+
+The recommended way to add an avatar script to your FST file is by manually editing the file to add your script url:
+
+1. Open the FST file for your avatar in the text editor of your choice.
+2. Add a line telling the avatar where to find the script file using the syntax ``script = [SCRIPT URL]``.
+
+.. code-block:: javascript
+    :emphasize-lines: 5
+    :caption: A sample of woody's FST file with a script added
+
+    name = mannequin
+    type = body+head
+    scale = 1
+    filename = mannequin/mannequin.fbx
+    script = mannequin/scripts/throw_ball.js
+    joint = jointNeck = Neck
+    joint = jointLean = Spine
+    joint = jointEyeLeft = LeftEye
+    joint = jointEyeRight = RightEye
+    joint = jointRoot = Hips
+    joint = jointLeftHand = LeftHand
+    joint = jointRightHand = RightHand
+    joint = jointHead = Head
+
+You can add multiple scripts to your avatar by adding multiple ``script = url`` lines.
+
+---------------------------
+Example of an Avatar Script
+---------------------------
+
+The following script makes your avatar throw balls when its right hand moves.
+
+.. code-block:: javascript
+    :caption: throw_ball.js
+
+    (function(){
+        "use strict"
+        let triggerDistance = 0.0;
+        const TRIGGER_THRESHOLD = 0.9;
+        const LOAD_THRESHOLD = 0.6
+        const rightHandIndex = MyAvatar.getJointIndex("RightHand");
+        const rightArmIndex = MyAvatar.getJointIndex("RightArm");
+        let triggered = false;
+
+        function fireBall(position, speed) {
+            const baseID = Entities.addEntity({
+                type: "Sphere",
+                color: { blue: 128, green: 128, red: 20 },
+                dimensions: { x: 0.1, y: 0.1, z: 0.1 },
+                position: position,
+                dynamic: true,
+                collisionless: false,
+                lifetime: 10, // Thrown fireball will despawn after 10 seconds
+                gravity: speed,
+                userData: "{ \"grabbableKey\": { \"grabbable\": true, \"kinematic\": false } }"
+            });
+            Entities.editEntity(baseID, { velocity: speed });
+        }
+
+        // VR users can push their right hand forwards from their shoulder to throw
+        Script.update.connect(function() {
+            const rightHandPos = MyAvatar.getJointPosition(rightHandIndex);
+            const rightArmPos = MyAvatar.getJointPosition(rightArmIndex);
+            const fireDir = Vec3.subtract(rightHandPos, rightArmPos);
+            const distance = Vec3.length(fireDir);
+            triggerDistance = distance > triggerDistance ? distance : triggerDistance;
+            if (!triggered) {
+                if (distance < LOAD_THRESHOLD * triggerDistance) {
+                    triggered = true;
+                }
+            } else if (distance > TRIGGER_THRESHOLD * triggerDistance) {
+                triggered = false;
+                fireBall(rightHandPos, Vec3.normalize(fireDir));
+            }
+        });
+        MyAvatar.scaleChanged.connect(function () {
+            triggerDistance = 0.0;
+        });
+
+        // Desktop users can press and release "x" to throw
+        function keyReleaseEvent(event) {
+            if ((event.text.toUpperCase() === "X") && !event.isAutoRepeat && !event.isShifted && !event.isMeta && !event.isControl && !event.isAlt) {
+                const rightHandPos = MyAvatar.getJointPosition(rightHandIndex);
+                const rightArmPos = MyAvatar.getJointPosition(rightArmIndex);
+                const fireDir = Vec3.subtract(rightHandPos, rightArmPos);
+                fireBall(rightHandPos, Vec3.normalize(fireDir));
+            }
+        }
+        // Runs desktop function whenever (any) key is released
+        Controller.keyReleaseEvent.connect(keyReleaseEvent);
+        // It is a good idea to clean up when the script stops
+        Script.scriptEnding.connect(function () {
+            print("removing key mapping");
+            Controller.keyReleaseEvent.disconnect(keyReleaseEvent);
+        });
+    }());
+
+
+This example script uses the `MyAvatar <https://apidocs.overte.org/MyAvatar.html>`_ namespace to determine if your avatar's hand moves. Upon detecting movement, the script makes your avatar launch balls. It also uses some other namespaces such as `Entities <https://apidocs.overte.org/Entities.html>`_ (to create the ball you will launch) and `Vec3 <https://apidocs.overte.org/Vec3.html>`_ (to determine the right positions and distances). Add it to your avatar to see how it works.
+
+**See Also**
+
+- `Get Started with Scripting <get-started-with-scripting>`_
+- `Write Your Own Scripts <write-scripts>`_
+- `API Reference <https://apidocs.overte.org>`_