Merge pull request #156 from ctrlaltdavid/dev/tidying

Distinguish empty strings from undefined

jsdoc/dev-mainpage.md

@@ -11,12 +11,14 @@ This SDK provides interfaces to:
 
 <hr />
 
-The top-level namespaces and classes provided for an application to use are, per the _Vircadia Web SDK Reference_:
+The primary top-level namespaces and classes provided for an application to use are, per the _Vircadia Web SDK Reference_:
 - `Vircadia`
 - `DomainServer`
 - `AudioMixer`
 - `AvatarMixer`
+- `EntityServer`
 - `MessageMixer`
+- `Camera`
 
 <hr />
 

jsdoc/sdk-mainpage.md

@@ -9,6 +9,17 @@ This SDK provides interfaces to:
 
 <hr />
 
+The primary top-level namespaces and classes provided for an application to use are:
+- `Vircadia`
+- `DomainServer`
+- `AudioMixer`
+- `AvatarMixer`
+- `EntityServer`
+- `MessageMixer`
+- `Camera`
+
+<hr />
+
 To use the API, import the namespaces and classes that you want to use &mdash; either from the SDK package installed in your
 project or directly from the SDK TypeScript.
 

src/domain/audio/AudioInput.ts

@@ -21,7 +21,7 @@ import SignalEmitter, { Signal } from "../shared/SignalEmitter";
  *  audio mixer.
  *  <p>C++: QAudioInput, QIODevice</p>
  *  @class AudioInput
- *  @property {MediaStream | null} audioInput - The user client's audio input stream.
+ *  @property {MediaStream|null} audioInput - The user client's audio input stream.
  *      <em>Write-only.</em>
  *      <p>This must be set to a non-null value only when the audio input isn't running (hasn't been started or has been
  *      stopped). Setting to <code>null</code> stops the audio input if it is running.</p>

src/domain/entities/ImageEntityItem.ts

@@ -56,15 +56,15 @@ class ImageEntityItem {
      *  <p>It has properties in addition to the {@link EntityProperties|common EntityProperties}. A property value may be
      *  undefined if it couldn't fit in the data packet sent by the server.</p>
      *  @typedef {object} ImageEntityProperties
-     *  @property {string | undefined} imageURL - The URL of the image to use.
-     *  @property {boolean | undefined} emissive - <code>true</code> if the image should be emissive (unlit), <code>false</code>
+     *  @property {string|undefined} imageURL - The URL of the image to use.
+     *  @property {boolean|undefined} emissive - <code>true</code> if the image should be emissive (unlit), <code>false</code>
      *      if it shouldn't.
-     *  @property {boolean | undefined} keepAspectRatio - <code>true</code> if the image should maintain its aspect ratio,
+     *  @property {boolean|undefined} keepAspectRatio - <code>true</code> if the image should maintain its aspect ratio,
      *      <code>false</code> if it shouldn't.
-     *  @property {rect | undefined} subImage - The portion of the image to display. If width or height are <code>0</code>, it
+     *  @property {rect|undefined} subImage - The portion of the image to display. If width or height are <code>0</code>, it
      *      defaults to the full image in that dimension.
-     *  @property {color | undefined} color - The color of the entity.
-     *  @property {number | undefined} alpha - The opacity of the image.
+     *  @property {color|undefined} color - The color of the entity.
+     *  @property {number|undefined} alpha - The opacity of the image.
      */
 
     /*@devdoc
@@ -117,10 +117,11 @@ class ImageEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_IMAGE_URL)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 imageURL = textDecoder.decode(new Uint8Array(data.buffer, data.byteOffset + dataPosition, length));
                 dataPosition += length;
+            } else {
+                imageURL = "";
             }
         }
 

src/domain/entities/ModelEntityItem.ts

@@ -67,19 +67,19 @@ class ModelEntityItem {
     /*@sdkdoc
      *  An animation is configured by the following properties.
      *  @typedef {object} AnimationProperties
-     *  @property {string | undefined} animationURL - The URL of the glTF or FBX file that has the animation. glTF files may be
+     *  @property {string|undefined} animationURL - The URL of the glTF or FBX file that has the animation. glTF files may be
      *      in JSON or binary format (".gltf" or ".glb" URLs respectively).
-     *  @property {boolean | undefined} animationAllowTranslation - <code>true</code> to enable translations contained in the
+     *  @property {boolean|undefined} animationAllowTranslation - <code>true</code> to enable translations contained in the
      *      animation to be played, <code>false</code> to disable translations.
-     *  @property {number | undefined} animationFPS - The speed in frames/s that the animation is played at.
-     *  @property {number | undefined} animationFrameIndex - The current frame being played in the animation.
-     *  @property {boolean | undefined} animationPlaying - <code>true</code> if the animation should play, <code>false</code>
+     *  @property {number|undefined} animationFPS - The speed in frames/s that the animation is played at.
+     *  @property {number|undefined} animationFrameIndex - The current frame being played in the animation.
+     *  @property {boolean|undefined} animationPlaying - <code>true</code> if the animation should play, <code>false</code>
      *      if it shouldn't.
-     *  @property {boolean | undefined} animationLoop - <code>true</code> if the animation is continuously repeated in a
+     *  @property {boolean|undefined} animationLoop - <code>true</code> if the animation is continuously repeated in a
      *      loop, <code>false</code> if it isn't.
-     *  @property {number | undefined} animationFirstFrame - The first frame to play in the animation.
-     *  @property {number | undefined} animationLastFrame - The last frame to play in the animation.
-     *  @property {boolean | undefined} animationHold - <code>true</code> if the rotations and translations of the last frame
+     *  @property {number|undefined} animationFirstFrame - The first frame to play in the animation.
+     *  @property {number|undefined} animationLastFrame - The last frame to play in the animation.
+     *  @property {boolean|undefined} animationHold - <code>true</code> if the rotations and translations of the last frame
      *     played are maintained when the animation stops playing, <code>false</code> if they aren't.
      */
 
@@ -89,38 +89,38 @@ class ModelEntityItem {
      *  <p>It has properties in addition to the {@link EntityProperties|common EntityProperties}. A property value may be
      *  undefined if it couldn't fit in the data packet sent by the server.</p>
      *  @typedef {object} ModelEntityProperties
-     *  @property {number | undefined} shapeType - The shape of the collision hull used if collisions are enabled.
-     *  @property {string | undefined} compoundShapeURL - The model file to use for the compound shape if shapeType is
+     *  @property {number|undefined} shapeType - The shape of the collision hull used if collisions are enabled.
+     *  @property {string|undefined} compoundShapeURL - The model file to use for the compound shape if shapeType is
      *      "compound".
-     *  @property {color | undefined} color - Currently not used.
-     *  @property {string | undefined} textures - A JSON string of texture name, URL pairs used when rendering the model in
+     *  @property {color|undefined} color - Currently not used.
+     *  @property {string|undefined} textures - A JSON string of texture name, URL pairs used when rendering the model in
      *      place of the model's original textures. Use a texture name from the originalTextures property to override that
      *      texture.  Only the texture names and URLs to be overridden need be specified; original textures are used where there
      *      are no overrides. You can use JSON.stringify() to convert a JavaScript object of name, URL pairs into a JSON string.
-     *  @property {string | undefined} modelURL - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary
+     *  @property {string|undefined} modelURL - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary
      *      format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may
      *      also be compressed in GZ format, in which case the URL ends in ".gz".
-     *  @property {vec3 | undefined} modelScale - The scale factor applied to the model's dimensions.
-     *  @property {boolean | undefined} jointRotationsSet - <code>true</code> values for joints that have had rotations
+     *  @property {vec3|undefined} modelScale - The scale factor applied to the model's dimensions.
+     *  @property {boolean|undefined} jointRotationsSet - <code>true</code> values for joints that have had rotations
      *      applied, <code>false</code> otherwise; Empty if none are applied or the model hasn't loaded.
-     *  @property {quat[] | undefined} jointRotations - Joint rotations applied to the model; Empty if none are applied or the
+     *  @property {quat[]|undefined} jointRotations - Joint rotations applied to the model; Empty if none are applied or the
      *      model hasn't loaded.
-     *  @property {boolean | undefined} jointTranslationsSet - <code>true</code> values for joints that have had translations
+     *  @property {boolean|undefined} jointTranslationsSet - <code>true</code> values for joints that have had translations
      *      applied, <code>false</code> otherwise; Empty if none are applied or the model hasn't loaded.
-     *  @property {vec3[] | undefined} jointTranslations - Joint translations applied to the model; Empty if none are applied or
+     *  @property {vec3[]|undefined} jointTranslations - Joint translations applied to the model; Empty if none are applied or
      *      the model hasn't loaded.
-     *  @property {boolean | undefined} groupCulled - <code>true</code> if the mesh parts of the model are LOD culled as a
+     *  @property {boolean|undefined} groupCulled - <code>true</code> if the mesh parts of the model are LOD culled as a
      *      group, <code>false</code> if separate mesh parts are LOD culled individually.
-     *  @property {boolean | undefined} relayParentJoints - <code>true</code> if when the entity is parented to an avatar,
+     *  @property {boolean|undefined} relayParentJoints - <code>true</code> if when the entity is parented to an avatar,
      *      the avatar's joint rotations are applied to the entity's joints; <code>false</code> if a parent avatar's joint
      *      rotations are not applied to the entity's joints.
-     *  @property {string | undefined} blendShapeCoefficients - A JSON string of a map of blendshape names to values. Only
+     *  @property {string|undefined} blendShapeCoefficients - A JSON string of a map of blendshape names to values. Only
      *      stores set values. When editing this property, only coefficients that you are editing will change; it will not
      *      explicitly reset other coefficients.
-     *  @property {boolean | undefined} useOriginalPivot - If <code>false</code>, the model will be centered based on its
+     *  @property {boolean|undefined} useOriginalPivot - If <code>false</code>, the model will be centered based on its
      *      content, ignoring any offset in the model itself. If <code>true</code>, the model will respect its original offset.
      *      Currently, only pivots relative to <code>{x: 0, y: 0, z: 0}</code> are supported.
-     *  @property {AnimationProperties | undefined} animation - An animation to play on the model.
+     *  @property {AnimationProperties|undefined} animation - An animation to play on the model.
      */
 
     /*@devdoc
@@ -160,12 +160,13 @@ class ModelEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_COMPOUND_SHAPE_URL)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 compoundShapeURL = textDecoder.decode(
                     new Uint8Array(data.buffer, data.byteOffset + dataPosition, length)
                 );
                 dataPosition += length;
+            } else {
+                compoundShapeURL = "";
             }
         }
 
@@ -183,25 +184,27 @@ class ModelEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_TEXTURES)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 textures = textDecoder.decode(
                     new Uint8Array(data.buffer, data.byteOffset + dataPosition, length)
                 );
                 dataPosition += length;
+            } else {
+                textures = "";
             }
         }
 
         let modelURL: string | undefined = undefined;
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_MODEL_URL)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 modelURL = textDecoder.decode(
                     new Uint8Array(data.buffer, data.byteOffset + dataPosition, length)
                 );
                 dataPosition += length;
+            } else {
+                modelURL = "";
             }
         }
 
@@ -312,12 +315,13 @@ class ModelEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_BLENDSHAPE_COEFFICIENTS)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 blendShapeCoefficients = textDecoder.decode(
                     new Uint8Array(data.buffer, data.byteOffset + dataPosition, length)
                 );
                 dataPosition += length;
+            } else {
+                blendShapeCoefficients = "";
             }
         }
 
@@ -331,12 +335,13 @@ class ModelEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_ANIMATION_URL)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 animationURL = textDecoder.decode(
                     new Uint8Array(data.buffer, data.byteOffset + dataPosition, length)
                 );
                 dataPosition += length;
+            } else {
+                animationURL = "";
             }
         }
 

src/domain/entities/ShapeEntityItem.ts

@@ -93,9 +93,9 @@ class ShapeEntityItem {
      *  <p>It has properties in addition to the {@link EntityProperties|common EntityProperties}. A property value may be
      *  undefined if it couldn't fit in the data packet sent by the server.</p>
      *  @typedef {object} ShapeEntityProperties
-     *  @property {Shape | undefined} shape - The shape of the entity.
-     *  @property {color | undefined} color - The color of the entity.
-     *  @property {number | undefined} alpha - The opacity of the entity, range <code>0.0 – 1.0</code>.
+     *  @property {Shape|undefined} shape - The shape of the entity.
+     *  @property {color|undefined} color - The color of the entity.
+     *  @property {number|undefined} alpha - The opacity of the entity, range <code>0.0 – 1.0</code>.
      */
 
     /*@devdoc

src/domain/entities/TextEntityItem.ts

@@ -98,26 +98,26 @@ class TextEntityItem {
      *  <p>It has properties in addition to the {@link EntityProperties|common EntityProperties}. A property value may be
      *  undefined if it couldn't fit in the data packet sent by the server.</p>
      *  @typedef {object} TextEntityProperties
-     *  @property {string | undefined} text - The text to display on the face of the entity. Text wraps if necessary to fit. New
+     *  @property {string|undefined} text - The text to display on the face of the entity. Text wraps if necessary to fit. New
      *      lines can be created using \n. Overflowing lines are not displayed.
-     *  @property {number | undefined} lineHeight - The height of each line of text (thus determining the font size).
-     *  @property {color | undefined} textEffectColor - The color of the text.
-     *  @property {number | undefined} textAlpha - The opacity of the text.
-     *  @property {number | undefined} backgroundAlpha - The opacity of the background.
-     *  @property {color | undefined} backgroundColor - The color of the background rectangle.
-     *  @property {number | undefined} leftMargin - The left margin, in meters.
-     *  @property {number | undefined} rightMargin - The right margin, in meters.
-     *  @property {number | undefined} topMargin - The top margin, in meters.
-     *  @property {number | undefined} bottomMargin - The bottom margin, in meters.
-     *  @property {boolean | undefined} unlit - <code>true</code> if the entity is unaffected by lighting, <code>false</code> if
+     *  @property {number|undefined} lineHeight - The height of each line of text (thus determining the font size).
+     *  @property {color|undefined} textEffectColor - The color of the text.
+     *  @property {number|undefined} textAlpha - The opacity of the text.
+     *  @property {number|undefined} backgroundAlpha - The opacity of the background.
+     *  @property {color|undefined} backgroundColor - The color of the background rectangle.
+     *  @property {number|undefined} leftMargin - The left margin, in meters.
+     *  @property {number|undefined} rightMargin - The right margin, in meters.
+     *  @property {number|undefined} topMargin - The top margin, in meters.
+     *  @property {number|undefined} bottomMargin - The bottom margin, in meters.
+     *  @property {boolean|undefined} unlit - <code>true</code> if the entity is unaffected by lighting, <code>false</code> if
      *      it is lit by the key light and local lights.
-     *  @property {string | undefined} font - The font to render the text with. It can be one of the following:
+     *  @property {string|undefined} font - The font to render the text with. It can be one of the following:
      *      "<code>Courier</code>", "<code>Inconsolata</code>", "<code>Roboto</code>", "<code>Timeless</code>", or a path to a
      *      .sdff file.
-     *  @property {TextEffect | undefined} textEffect - The effect that is applied to the text.
-     *  @property {color | undefined} textColor - The color of the effect.
-     *  @property {number | undefined} textEffectThickness - The magnitude of the text effect, range 0.0 – 0.5.
-     *  @property {TextAlignment | undefined} textAlignment - How the text is aligned against its background.
+     *  @property {TextEffect|undefined} textEffect - The effect that is applied to the text.
+     *  @property {color|undefined} textColor - The color of the effect.
+     *  @property {number|undefined} textEffectThickness - The magnitude of the text effect, range 0.0 – 0.5.
+     *  @property {TextAlignment|undefined} textAlignment - How the text is aligned against its background.
      */
 
     /*@devdoc
@@ -154,10 +154,11 @@ class TextEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_TEXT)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 text = textDecoder.decode(new Uint8Array(data.buffer, data.byteOffset + dataPosition, length));
                 dataPosition += length;
+            } else {
+                text = "";
             }
         }
 
@@ -233,10 +234,11 @@ class TextEntityItem {
         if (propertyFlags.getHasProperty(EntityPropertyFlags.PROP_FONT)) {
             const length = data.getUint16(dataPosition, UDT.LITTLE_ENDIAN);
             dataPosition += 2;
-
             if (length > 0) {
                 font = textDecoder.decode(new Uint8Array(data.buffer, data.byteOffset + dataPosition, length));
                 dataPosition += length;
+            } else {
+                font = "";
             }
         }