Script overte by zedwick · Pull Request #71 · overte-org/overte-docs-sphinx

zedwick · 2026-02-22T14:48:07Z

This PR brings the Script section of the docs up to date.

Some files have been converted from markdown to reStructuredText to standardise the docs, however usually only when I felt it necessary or simpler for the changes I intended to make.
Removed recommendations to use incomplete or non-working functionality.
Corrected instructions where the interface had changed, including images where appropriate.
Example JavaScript code has been updated to use Strict mode.
Changed examples to accommodate and entertain both VR and Desktop users.
Rewrote text to remove negative framing in certain places
Corrected inaccuracies about the current features of Overte
Tested all example code to ensure they work, and fixed them if they did not.
Improved clarity in some areas
Other miscellaneous changes

* De-emphasise Overte being just a VR platform * Don't use var in example scripts

* Convert from markdown to reStructuredText format * Fix syntax error in example code * Expand Equip Item section with full working example * Add "use strict" and remove vars in example code

* console.log in an exported function will not show in logs

…redText

…ict"

* "use strict", etc. * Also add a way for desktop users to try out the avatar script by pressing "x" on their keyboard.

* Remove section on using Package Model to add scripts; does not work * Replace image of text editor with code block, including highlighted line

* Encourage use of server entity script in some situations * Correct steps to add a client entity script, with scripts page icon. * Example script now wil "use strict", etc.

* Correct steps to attach a Server Entity Script to an Entity * Example script will now "use strict", etc.

* I don't mean to alarm anyone, but it is now closer to 40 years since the 80s. A slight change to the wording to make this tutorial timeless.

* Loading a script from the UI will load it persistently

* clickDownOnEntity only responds to mouse click events; cannot be used in VR with controllers * mousePressOnEntity responds to both mouse click and controller trigger events

source/script/assignment-client-scripts.rst

JulianGro · 2026-02-27T10:19:54Z

source/script/assignment-client-scripts.rst

+
+1. Open your 'Domain Administration Panel'. If you are on a local sandbox, 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'. 


I assume these are the same as the assignment client script under http://localhost:40100/assignment ?
If you think so too, maybe we should open an issue about streamlining the UI there. It is quite confusing to have more or less the same thing in two different places.

source/script/avatar-scripts.rst

JulianGro · 2026-02-27T10:40:52Z

source/script/avatar-scripts.rst

+    (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 = getPointingDirection();
+                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);
+        });
+    }());


Suggested change

(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 = getPointingDirection();

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);

});

}());

(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 = getPointingDirection();

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);

});

}());

The indentation of the code-block directive is 3 spaces, so by adding 4 spaces, the resulting code-block has everything indented one space too far. You can change the indentation of the directive to 4 spaces, to avoid having to use 3 spaces in the first indentation instead. (See my other comment/suggestion.)

JulianGro · 2026-02-27T10:41:35Z

source/script/avatar-scripts.rst

+.. code-block:: javascript
+   :caption: throw_ball.js


Suggested change

.. code-block:: javascript

:caption: throw_ball.js

.. code-block:: javascript

:caption: throw_ball.js

If you prefer having 4-space indentation for the directive, instead of having the first indentation of the script be 3 spaces.

JulianGro · 2026-02-27T12:43:13Z

source/script/server-entity-scripts.rst

+Server Entity Scripts
+#####################
+
+You can make content in Overte interactive by attaching scripts to entities. *Server entity scripts* are entity scripts that run on the server (or domain) that hosts the entity. These scripts run persistently in a domain, even if there are no users present. This means that there is only one instance of the script is running at a time, and it is running on the server. Any behavior that is controlled by your script will be seen and heard by everyone in the domain.


Suggested change

You can make content in Overte interactive by attaching scripts to entities. *Server entity scripts* are entity scripts that run on the server (or domain) that hosts the entity. These scripts run persistently in a domain, even if there are no users present. This means that there is only one instance of the script is running at a time, and it is running on the server. Any behavior that is controlled by your script will be seen and heard by everyone in the domain.

You can make content in Overte interactive by attaching scripts to entities. *Server entity scripts* are entity scripts that run on the server (or domain) that hosts the entity. These scripts run persistently in a domain, even if there are no users present. This means that there is only one instance of the script running at a time, and it is running on the server. Any behavior that is controlled by your script will be seen or heard by everyone in the domain.

JulianGro · 2026-02-27T12:43:29Z

source/script/server-entity-scripts.rst

+
+.. note:: An entity can have multiple server entity scripts attached to it, but all of these must be through a single file URL.
+
+.. |scripts-icon| image:: _images/create-properties-scripts-icon.png


Too low contrast.

JulianGro · 2026-02-27T12:49:02Z

source/script/server-entity-scripts.rst

+3. In the **Create** app, go to the 'Properties' tab and select the Scripts icon. |scripts-icon|
+4. For 'Server Script', enter the URL to your server entity script.
+
+.. note:: An entity can have multiple server entity scripts attached to it, but all of these must be through a single file URL.


Does this apply to client scripts as well? I had no idea we could do this, and thought this is what we added Script Entities for.

JulianGro · 2026-02-27T12:51:19Z

source/script/server-entity-scripts.rst

@@ -0,0 +1,76 @@
+#####################
+Server Entity Scripts
+#####################


This page should probably mention the Developer → Scripting → Entity Script Server Log.

JulianGro · 2026-02-27T12:55:40Z

source/script/write-scripts.md


 <div class="admonition note">
    <p class="admonition-title">Note</p>
    <p>Entity scripts, unlike interface scripts, are in containing functions. The example scripts here cannot be attached to an entity (and be used as an entity script) unless they are in a containing function ``function() {}``.</p>


Suggested change

<p>Entity scripts, unlike interface scripts, are in containing functions. The example scripts here cannot be attached to an entity (and be used as an entity script) unless they are in a containing function <code>function() {}</code>.</p>

JulianGro · 2026-02-27T13:06:16Z

You can apply multiple suggestions at once from the Files changed page.

Co-authored-by: Julian Groß <julian.g@posteo.de>

zedwick added 24 commits February 2, 2026 23:00

Improve script/get-started-with-scripting

4d481be

Minor improvements to script/write-scripts

7d22d19

* De-emphasise Overte being just a VR platform * Don't use var in example scripts

Improve script/js-tips

7574c15

* Convert from markdown to reStructuredText format * Fix syntax error in example code * Expand Equip Item section with full working example * Add "use strict" and remove vars in example code

Convert script/interface-scripts from markdown to reStructuredText

563c6ba

Fix example code in script/js-tips

8727dfe

* console.log in an exported function will not show in logs

Final touches to script/interface-scripts

86715fd

Covnerted script/assignment-client-scripts from markdown to reStructu…

1c43615

…redText

Update code example in script/assignment-client-scripts with "use str…

7284865

…ict"

Convert script/avatar-scripts from markdown to reStructuredText

fc26577

Update example script in script/avatar-scripts

01b8f55

* "use strict", etc. * Also add a way for desktop users to try out the avatar script by pressing "x" on their keyboard.

Improve script/avatar-scripts

36a4473

* Remove section on using Package Model to add scripts; does not work * Replace image of text editor with code block, including highlighted line

Rename script/client-entity-scripts from .md to .rst

b4b53bf

Remove image file already removed from script/avatar-scripts

5bcf4e8

script/client-entity-scripts markdown -> reStructuredText

f26b1ad

Improve script/client-entity-scripts

3f5617b

* Encourage use of server entity script in some situations * Correct steps to add a client entity script, with scripts page icon. * Example script now wil "use strict", etc.

Renamed script/server-entity-scripts .md -> .rst

f0eb1de

Convert script/server-entity-scripts from Markdown to reStructuredText

1793b6d

Improve script/server-entity-scripts

ea6e9e2

* Correct steps to attach a Server Entity Script to an Entity * Example script will now "use strict", etc.

Minor improvement to script/midi-tutorial

86ed9d5

* I don't mean to alarm anyone, but it is now closer to 40 years since the 80s. A slight change to the wording to make this tutorial timeless.

Revert the removal of a single letter which had been removed incorrectly

d6dc17b

Overte scripting now runs on the V8 engine

5bcb3fb

* Loading a script from the UI will load it persistently

Add note about use of to 3 script pages.

7787dc0

Update the example interface script to be a little more interesting.

44dc419

Use mousePressOnEntity in client entity script example

e7f2281

* clickDownOnEntity only responds to mouse click events; cannot be used in VR with controllers * mousePressOnEntity responds to both mouse click and controller trigger events

zedwick marked this pull request as ready for review February 24, 2026 12:58

JulianGro requested changes Feb 27, 2026

View reviewed changes

Apply suggestions from code review

e0c4a91

Co-authored-by: Julian Groß <julian.g@posteo.de>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Script overte#71

Script overte#71
zedwick wants to merge 25 commits intooverte-org:masterfrom
zedwick:script_overte

zedwick commented Feb 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro Feb 27, 2026

Uh oh!

JulianGro commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		.. note:: An entity can have multiple server entity scripts attached to it, but all of these must be through a single file URL.

		.. \|scripts-icon\| image:: _images/create-properties-scripts-icon.png


	<p>Entity scripts, unlike interface scripts, are in containing functions. The example scripts here cannot be attached to an entity (and be used as an entity script) unless they are in a containing function <code>function() {}</code>.</p>

Conversation

zedwick commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JulianGro commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zedwick commented Feb 22, 2026 •

edited

Loading