hifi scripting api proposal (Vec3, Quat, Color, Entity).js

// All existing APIs will be available. The new API calls will include the following:

// To see the benefits, see this example (diff):
// https://gist.github.com/SeijiEmery/2a01a04a7d21e3408f17eb20be539d0e/revisions

// Constructor:
function Vec3 (arg0: Vec3 | number, y: number?, z: number?)

    var v1 = new Vec3(1.0, 2.0, 3.0);
    var v2 = new Vec3({ x: 1.0, y: 2.0, z: 3.0 })
    var v3 = new Vec3({ x: 1.0, z: 3.0 })   // missing values default to 0.0
    var v4 = new Vec3(someFunctionThatReturnsAVec3LikeObject())

// Arithmetic methods always return a _new_ Vec3 and are not mutating.
function Vec3.prototype.add             (other: Vec3): Vec3
function Vec3.prototype.subtract        (other: Vec3): Vec3

// Implements scaling (number), componentwise multiplication (Vec3),
// or rotation / quaternion multiplication (Quat)
function Vec3.prototype.multiply        (other: number | Vec3 | Quat): Vec3
function Vec3.prototype.divide          (other: number | Vec3): Vec3
function Vec3.prototype.cross           (other: Vec3): Vec3

function Vec3.prototype.dot             (other: Vec3): number
function Vec3.prototype.distance        (other: Vec3): number
function Vec3.prototype.distanceSquared (other: Vec3): number

// This is .magnitude() and not .length(), since overriding .length() is
// problematic in JS6. If there is significant pushback on this, we could add 
// .length as a property.
function Vec3.prototype.magnitude (): number
function Vec3.prototype.magnitudeSquared (): number

// Could output either:
//  1. "Vec3(<x>, <y>, <z>)"
//  2. "{ x: <x>, y: <y>, z: <z> }"
// or any other format – what do the devs want?
//
// Needless to say this means you would no longer have to write
// JSON.stringify(vec) to print vectors.
function Vec3.prototype.toString (): string

// Returns a new normalized vector.
function Vec3.prototype.normalized (): Vec3

// Normalizes this vector; returns void.
// Or could return this (chaining), though the type signature is less
// confusing if it has no return value.
function Vec3.prototype.normalize ()

// To / from polar coordinates, returns a Vec3.
function Vec3.prototype.toPolar   (): Vec3
function Vec3.prototype.fromPolar (): Vec3

// Converts to / from degrees / radians. Useful if working with the Quat api :)
function Vec3.prototype.toDegrees (): Vec3
function Vec3.prototype.toRadians (): Vec3

// Would be added if / whenever a Color object was added.
// Would be equivalent to new Color((myVec.x * 255.0) | 0, (myVec.y * 255.0) | 0, (myVec.z * 255.0) | 0)
function Vec3.prototype.toColor (): Color

// This replaces Vec3.equal() and Vec3.withinEpsilon()
// The second parameter is optional and defaults to 0.0, ie Vec3.equal()
function Vec3.prototype.equals (other: Vec3, epsilon: number = 0.0): boolean

// Implements assignment, ie. myVec1 = myVec2. Returns this.
function Vec3.prototype.assign (other: Vec3): Vec3

// Returns the angle between two vectors. orientedAngle() has the same behavior as Vec3.orientedAngle()
function Vec3.prototype.angle (other: Vec3): number
function Vec3.prototype.orientedAngle (other: Vec3, reference: Vec3): number

// Linear and spherical interpolation, a la unity.
// lerp() is currently called mix(), and could be called that or interpolate()
// slerp() could be called sphericallyInterpolate (or something), though that's a lot more awkward
// factor will not be clamped to [0, 1], since the user could do that and otherwise wierd behavior
// could be desired.
function Vec3.prototype.lerp  (other: Vec3, factor: number): Vec3
function Vec3.prototype.slerp (other: Vec3, factor: number): Vec3

// Creates a rotation quaternion using this vector as the axis, as in Quat.angleAxis()
// could be named toRotation(), toRotationAboutAxis(), or something else...
function Vec3.rotation (angle: number): Quat

// I think that's it but I might've missed something; if there are any requests please let me know :)


// Quaternion constructor
function Quat (arg0: Quat | number, x: number?, y: number?, z: number?, w: number?)

    var q1 = new Quat({ x: 0.95, y: 0.23, z: 0.44, w: 0.56 })
    var q2 = new Quat(0.95, 0.23, 0.44, 0.56)
    var q3 = new Quat(someFunctionThatReturnsAQuatLikeObject())

// Methods TBD, but would match existing API. Like existing API, all calls would return
// angles in degrees, with separate versions for from radians

// Here's a few examples though:
function Quat.prototype.getEulerAngles (): Vec3
function Quat.fromEulerAngles (angles: Vec3): Quat
function Quat.fromAngleAxis   (angle: number, axis: Vec3): Quat

function Quat.prototype.getEulerAnglesRadians (): Vec3
function Quat.fromEulerAnglesRadians (angles: Vec3): Quat
function Quat.fromAngleAxisRadians (angle: number, axis: Vec3): Quat

readonly property Quat.forward:  Vec3   // or .fwd?
readonly property Quat.backward: Vec3   // or .back?
readonly property Quat.left:     Vec3
readonly property Quat.right:    Vec3
readonly property Quat.up:       Vec3
readonly property Quat.down:     Vec3


//
// Additional APIs (would be implemented later): 
//


// Color: note that hifi is entirely lacking in a js Color API atm;
// currently is using a wrapped / converted xColor struct from the c++ side.
// Implementing this might take a bit more time since existing API calls would
// have to be converted to return this object type.

function Color (arg0: Color | String | number, green: number?, blue: number?)

    var c1 = new Color(255, 100, 0)
    var c2 = new Color("#ffaa00")
    var c3 = new Vec3(1.0, 0.5, 0.0).toColor();

function Color.prototype.toVector (): Vec3  // or .toVec3()?

function Color.fromVector (color: Vec3): Color
function Color.fromHUSV   (color: Vec3 | string): Color
function Color.fromHUSL   (color: Vec3 | string): Color
// and add in any other color formats you might want...


// Entities: an object-oriented entity API would be highly desirable.
// There are lots of bells and whistles that could be added, but the simplest
// (and sanest) addition would just be to add a barebones Entity object
// and expand on it later. 
//
// This would look something like the following, possibly with additional
// methods and javascript properties to access full entity properties.
//
// Entity would also be entirely _optional_, and just function
// as an easier way to use the existing Entities API in a way that
// fits most users use cases. Incremental improvement is better than
// being too ambitious and breaking things.
//
// Note: this is just illustrative; this is NOT all valid JS.

function Entity (arg0: object | string) {
    if (typeof(arg0) === 'object') {
        this.id = null;
        this.properties = arg0;
        this.create();
    } else {
        this.id = arg0;
        this.properties = Entities.getEntityProperties(this.id);
    }
}
function Entity.prototype.create () {
    if (!this.id) {
        this.id = Entities.addEntity(this.properties);
    }
}
function Entity.prototype.update () {
    if (this.id) {
        Entities.editEntity(this.id, this.properties);
    }
}
function Entity.prototype.destroy () {
    if (this.id) {
        Entities.deleteEntity(this.id);
        this.id = null;
    }
}

// Also, here's a way to add a simple form of ownership / automatic entity destruction to scripts

// Hide this in a closure
var __scriptSpawnedEntities = new Array();
Script.scriptEnding.connect(function(){
    __scriptSpawnedEntities.forEach(function(entity) {
        if (entity.properties.owner === 'script') {     // Or, if scripts have UUIDs, could use that...
            entity.destroy();
        }
    });
});

function Entity (/* ... */) {
    // ...
    this.properties.owner = this.properties.owner || 'script';
    // ...
}
function Entity.prototype.create () {
    __scriptSpawnedEntities[this.id] = this;
    // ...
}
function Entity.prototype.destroy () {
    delete __scriptSpawnedEntities[this.id];
    // ...
}