Unity Academy User Agreement, GUI (Button / Label) Functions and Bug Fixes (#203)

* Unity Academy User Agreement Update and Bug Fixes

* Fixed a bug

* Fixed a bug about checking User Agreement checkbox status

* Unity Academy GUI (Button & Label) functions

* Improved Unity Academy GUI functions

* Unity Academy - Finished GUI functions

* Update documentation

Author: larrywang0701

src/bundles/unity_academy/UnityAcademy.tsx

@@ -162,6 +162,8 @@ class UnityAcademyJsInteropContext {
   private unityInstanceState; // [set by interop]
   private guiData : any[]; // [get / clear by interop]
   public dimensionMode;
+  private isShowingUnityAcademy : boolean; // [get by interop]
+  private latestUserAgreementVersion : string;
 
   constructor() {
     this.unityInstance = null;
@@ -180,6 +182,8 @@ class UnityAcademyJsInteropContext {
     };
     this.targetFrameRate = 30;
 
+    this.latestUserAgreementVersion = 'unknown';
+    this.getLatestUserAgreementVersion();
 
     // [ Why I don't put this into my module's own context? ]
     // Since Unity Academy application needs to access this from the WASM side, and the Unity Academy WASM side can not access the module context under the js-slang evaluation scope since Unity Academy app is running totally separated from js-slang in the WASM virtual machine.
@@ -191,6 +195,7 @@ class UnityAcademyJsInteropContext {
     document.body.appendChild(this.unityContainerElement);
     ReactDOM.render(<UnityComponent />, this.unityContainerElement);
     this.setShowUnityComponent(0);
+    this.isShowingUnityAcademy = false;
 
     this.gameObjectIdentifierWrapperClass = GameObjectIdentifier;
 
@@ -243,6 +248,7 @@ class UnityAcademyJsInteropContext {
 
   setShowUnityComponent(resolution: number) {
     const toShow = resolution > 0;
+    this.isShowingUnityAcademy = toShow;
     const sendMessageFunctionName = 'SendMessage';
     if (toShow) {
       (this.unityContainerElement as any).style.visibility = 'visible';
@@ -304,6 +310,40 @@ class UnityAcademyJsInteropContext {
     return this.unityInstanceState === 'Ready';
   }
 
+  private getLatestUserAgreementVersion() : void {
+    const jsonUrl = `${UNITY_ACADEMY_BACKEND_URL}user_agreement.json`;
+    const xhr = new XMLHttpRequest();
+    xhr.onreadystatechange = () => {
+      if (xhr.readyState === 4 && xhr.status === 200) {
+        this.latestUserAgreementVersion = JSON.parse(xhr.responseText).version;
+      }
+    };
+    xhr.open('GET', jsonUrl, true);
+    xhr.send();
+  }
+
+  getUserAgreementStatus() : string {
+    const agreedUserAgreementVersion = localStorage.getItem('unity_academy_agreed_user_agreement_version');
+    if (agreedUserAgreementVersion === null || agreedUserAgreementVersion === 'unagreed' || agreedUserAgreementVersion === 'unknown') {
+      return 'unagreed';
+    }
+    if (this.latestUserAgreementVersion === 'unknown') {
+      return 'unagreed';
+    }
+    if (agreedUserAgreementVersion !== this.latestUserAgreementVersion) {
+      return 'new_user_agreement';
+    }
+    return 'agreed';
+  }
+
+  setUserAgreementStatus(agree : boolean) : void {
+    if (agree) {
+      localStorage.setItem('unity_academy_agreed_user_agreement_version', this.latestUserAgreementVersion);
+    } else {
+      localStorage.setItem('unity_academy_agreed_user_agreement_version', 'unagreed');
+    }
+  }
+
   instantiateInternal(prefabName : string) : GameObjectIdentifier {
     let prefabExists = false;
     const len = this.prefabInfo.prefab_info.length;
@@ -443,6 +483,7 @@ class UnityAcademyJsInteropContext {
     const eulerY = Math.atan2(deltaVector.x, deltaVector.z);
     gameObject.transform.rotation.x = eulerX * 180 / Math.PI;
     gameObject.transform.rotation.y = eulerY * 180 / Math.PI;
+    gameObject.transform.rotation.z = 0;
   }
 
   gameObjectDistanceInternal(gameObjectIdentifier_A : GameObjectIdentifier, gameObjectIdentifier_B : GameObjectIdentifier) : number {
@@ -562,24 +603,26 @@ class UnityAcademyJsInteropContext {
     return this.getGameObjectIdentifierForPrimitiveGameObject('MainCamera');
   }
 
-  onGUI_Label(content : string, x : number, y : number) : void {
+  onGUI_Label(content : string, x : number, y : number, fontSize : number) : void {
     content = content.replaceAll('|', ''); // operator '|' is reserved as gui data separator in Unity Academy
     const newLabel = {
       type: 'label',
       content,
       x,
       y,
+      fontSize,
     };
     this.guiData.push(newLabel);
   }
 
-  onGUI_Button(text : string, x: number, y : number, onClick : Function) : void {
+  onGUI_Button(text : string, x: number, y : number, fontSize : number, onClick : Function) : void {
     text = text.replaceAll('|', ''); // operator '|' is reserved as gui data separator in Unity Academy
     const newButton = {
       type: 'button',
       text,
       x,
       y,
+      fontSize,
       onClick,
     };
     this.guiData.push(newButton);
@@ -608,19 +651,19 @@ class UnityAcademyJsInteropContext {
 }
 
 export function initializeModule(dimensionMode : string) {
-  let INSTANCE = getInstance();
-  if (INSTANCE !== undefined) {
-    if (!INSTANCE.isUnityInstanceReady()) {
+  let instance = getInstance();
+  if (instance !== undefined) {
+    if (!instance.isUnityInstanceReady()) {
       throw new Error('Unity instance is not ready to accept a new Source program now. Please try again later.');
     }
-    if (INSTANCE.unityInstance === null) {
-      INSTANCE.reloadUnityAcademyInstanceAfterTermination();
+    if (instance.unityInstance === null) {
+      instance.reloadUnityAcademyInstanceAfterTermination();
     }
-    INSTANCE.dimensionMode = dimensionMode;
-    INSTANCE.reset();
+    instance.dimensionMode = dimensionMode;
+    instance.reset();
     return;
   }
 
-  INSTANCE = new UnityAcademyJsInteropContext();
-  INSTANCE.dimensionMode = dimensionMode;
+  instance = new UnityAcademyJsInteropContext();
+  instance.dimensionMode = dimensionMode;
 }

src/bundles/unity_academy/functions.ts

@@ -125,8 +125,11 @@ export function set_update(gameObjectIdentifier : GameObjectIdentifier, updateFu
 
 
 /**
- * Creates a new GameObject from an existing Prefab
- * <br><b>3D mode only</b>
+ * Creates a new GameObject from an existing Prefab<br>
+ * <br>
+ * <b>3D mode only</b><br>
+ * <br>
+ * Available Prefab Information: <a href = 'https://unity-academy.s3.ap-southeast-1.amazonaws.com/webgl_assetbundles/prefab_info.html' rel="noopener noreferrer" target="_blank">Click Here</a>
  *
  * @param prefab_name The prefab name
  * @return the identifier of the newly created GameObject
@@ -299,7 +302,9 @@ export function set_rotation_euler(gameObjectIdentifier : GameObjectIdentifier,
 }
 
 /**
- * Returns the scale of a given GameObject
+ * Returns the scale (size factor) of a given GameObject
+ * <br>
+ * By default the scale of a GameObject is (1, 1, 1)
  * @param gameObjectIdentifier The identifier for the GameObject that you want to get scale for.
  * @return the scale represented in an array with three elements: [x, y, z]
  *
@@ -313,7 +318,9 @@ export function get_scale(gameObjectIdentifier : GameObjectIdentifier) : Array<N
 }
 
 /**
- * Set the scale of a given GameObject
+ * Set the scale (size) of a given GameObject
+ * <br>
+ * By default the scale of a GameObject is (1, 1, 1). Changing the scale of a GameObject along one axis will lead to a stretch or squeeze of the GameObject along that axis.
  *
  * @param gameObjectIdentifier The identifier for the GameObject that you want to change scale for.
  * @param x The x component for the scale.
@@ -879,42 +886,69 @@ export function on_collision_exit(gameObjectIdentifier : GameObjectIdentifier, e
 
 
 /**
- * Draw a text (string) on the screen with given screen position.<br>
- * The origin of screen space is upper-left corner and the positive Y axis is downward.<br>
- * You should put this under the `Update` function (or a function that is called by the `Update` function) to keep the text in every frame.
+ * Draw a text (string) on the screen with given <b>screen space position</b> in the current frame.<br>
+ * The origin of screen space is upper-left corner and the positive Y direction is downward.<br>
+ * The drawn text will only last for one frame. You should put this under the `Update` function (or a function that is called by the `Update` function) to keep the text stays in every frame.<br>
  *
  * @param content The string you want to display on screen.
  * @param x The x coordinate of the text (in screen position).
  * @param y The y coordinate of the text (in screen position).
+ * @param fontSize The size of the text
  * @category Graphical User Interface
  */
-export function gui_label(content : string, x : number, y : number) : void {
+export function gui_label(content : string, x : number, y : number, fontSize : number) : void {
   checkUnityAcademyExistence();
+  checkParameterType(content, 'string');
   checkParameterType(x, 'number');
   checkParameterType(y, 'number');
+  checkParameterType(fontSize, 'number');
   getInstance()
-    .onGUI_Label(content, x, y);
+    .onGUI_Label(content, x, y, fontSize);
 }
 
 
 /**
- * Make a button on the screen with given screen position. When user clicks the button, the `onClick` function will be called.<br>
- * The origin of screen space is upper-left corner and the positive Y axis is downward.<br>
- * You should put this under the `Update` function (or a function that is called by the `Update` function) to keep the button in every frame.
+ * Make a button on the screen with given <b>screen space position</b> in the current frame. When user clicks the button, the `onClick` function will be called.<br>
+ * The origin of screen space is upper-left corner and the positive Y direction is downward.<br>
+ * The drawn button will only last for one frame. You should put this under the `Update` function (or a function that is called by the `Update` function) to keep the button stays in every frame.
+ * <br>
+ * <br>
+ * If this function is called by a lifecycle event function, then the `onClick` function in the fourth parameter could also be considered as a lifecycle event function.<br>
+ * This means that you can use other functions from this module inside the `onClick` function, even though the functions are not under the `Outside Lifecycle` category.<br>
+ * For example, the code piece below
+ * ```
+ * import {init_unity_academy_3d, set_start, set_update, instantiate, gui_button, set_position }
+ * from "unity_academy";
+ * init_unity_academy_3d();
+ *
+ * const cube = instantiate("cube");
+ *
+ * const cube_update = (gameObject) => {
+ *   gui_button("Button", 1000, 300, ()=>
+ *     set_position(gameObject, 0, 10, 6) // calling set_position inside the onClick function
+ *   );
+ * };
+
+ * set_update(cube, cube_update);
+ * ```
+ * is correct.<br>
  *
  * @param text The text you want to display on the button.
  * @param x The x coordinate of the button (in screen position).
  * @param y The y coordinate of the button (in screen position).
  * @param onClick The function that will be called when user clicks the button on screen.
+ * @param fontSize The size of the text inside the button.
  * @category Graphical User Interface
  */
-export function gui_button(text : string, x: number, y : number, onClick : Function) : void {
+export function gui_button(text : string, x: number, y : number, fontSize : number, onClick : Function) : void {
   checkUnityAcademyExistence();
+  checkParameterType(text, 'string');
   checkParameterType(x, 'number');
   checkParameterType(y, 'number');
+  checkParameterType(fontSize, 'number');
   checkParameterType(onClick, 'function');
   getInstance()
-    .onGUI_Button(text, x, y, onClick);
+    .onGUI_Button(text, x, y, fontSize, onClick);
 }
 
 /**

src/bundles/unity_academy/index.ts

@@ -5,8 +5,9 @@
  * <br>
  * <b>Code Examples: </b><a href = 'https://unity-academy.s3.ap-southeast-1.amazonaws.com/code_examples.html' rel="noopener noreferrer" target="_blank">Click Here</a><br>
  * <b>Prefab Information: </b><a href = 'https://unity-academy.s3.ap-southeast-1.amazonaws.com/webgl_assetbundles/prefab_info.html' rel="noopener noreferrer" target="_blank">Click Here</a><br>
+ * <b>User Agreement: </b><a href = 'https://unity-academy.s3.ap-southeast-1.amazonaws.com/user_agreement.html' rel="noopener noreferrer" target="_blank">Click Here</a><br>
  * <br>
- * <b><u>Note that you need to use this module with a 'Native' variant of Source language, otherwise you may get strange errors.</u></b>
+ * <b><u>Note that you need to use this module with a '<i>Native</i>' variant of Source language, otherwise you may get strange errors.</u></b>
  * <br>
  * <br>
  * <b>Lifecycle Event Functions</b><br>
@@ -24,15 +25,19 @@
  * ● ===>`Update` is called on every GameObject once in every frame after `Start` have been called. <br>
  * ● For the three collision detaction lifecycle event functions, please refer to `on_collision_enter`, `on_collision_stay` and `on_collision_exit` functions under the `Physics - Collision` category.<br>
  * ● You can not bind multiple lifecycle functions of the same type to the same GameObject. For example, you can't bind two `Update` functions to the same GameObject. In this case, previously binded `Update` functions will be overwritten by the latest binded `Update` function.<br><br>
- * <u><b>[IMPORTANT]</b> All functions in this module that is NOT under the "<b>Outside Lifecycle</b>" or "Maths" category need to call by Unity Academy lifecycle event functions (Start or Update) to work correctly. Failure to follow this rule may lead to noneffective or incorrect behaviors of the functions and may crash the Unity Academy instance.</u><br>
+ * <u><b>[IMPORTANT]</b> All functions in this module that is NOT under the "<b>Outside Lifecycle</b>" or "Maths" category need to call by Unity Academy lifecycle event functions (directly or intermediately) to work correctly. Failure to follow this rule may lead to noneffective or incorrect behaviors of the functions and may crash the Unity Academy instance.</u><br>
  * For example:
  * ```
- * import {init_unity_academy_3d, instantiate, set_start, set_update, set_position} from 'unity_academy';
+ * import {init_unity_academy_3d, instantiate, set_start, set_update, set_position, set_rotation_euler} from 'unity_academy';
  * init_unity_academy_3d(); // Correct, since this function is under the "Outside Lifecycle" category and it can be called outside lifecycle event functions.
  * const cube = instantiate("cube"); // Correct
  * set_position(cube, 1, 2, 3); // WRONG, since set_position should ONLY be called inside a lifecycle event function
  * function my_start(gameObject){ // A sample Start event function which will be binded to cube by my_start later.
  *     set_position(gameObject, 1, 2, 3); // Correct, since the call to set_position is inside a lifecycle event function
+ *     something_else(gameObject);
+ * }
+ * function something_else(obj){
+ *    set_rotation_euler(obj, 0, 45, 45);  // Correct, since the function "set_rotation_euler" is intermediately called by the lifecycle event function "my_start" through "something_else"
  * }
  * set_start(cube, my_start); // Correct
  * ```
@@ -44,16 +49,16 @@
  * <br>
  * <br>
  * <b>Key differences between 2D and 3D mode</b><br>
- * ● In 2D mode the main camera renders the scene in <b>orthographic</b> mode (Z position is used to determine sequence when sprites overlapping), whereas in 3D mode the camera renders the scene in <b>perspective</b> mode. Moreover, 3D mode and 2D mode have different kinds of default camera controller.<br>
- * ● In 2D mode, due to the loss of one dimension, for some values and axis in 3D coordinate system, they sometimes behaves differently with 3D mode. For example, some coordinate values is ignored in 2D mode. Whereas in 3D mode you can use the fully-supported 3D coordinate system. (Actually, in general, Unity Academy just simply uses 3D space and an orthographic camera to simulate 2D space.)<br>
- * ● In 2D mode you need to use <b>instantiate_sprite</b> to create new GameObjects, whereas in 3D mode you need to use <b>instantiate</b> to create new GameObjects.<br>
- * ● In 2D mode Unity Academy will use Rigidbody2D and 2D colliders like BoxCollider2D for physics engine (certain values for 3D physics engine in 2D physics engine is ignored and will always be zero), whereas in 3D mode Unity Academy use regular 3D rigidbody and 3D colliders to simulate 3D physics.<br>
- * ● In 2D mode playing frame animations for sprite GameObjects is currently unavailable, whereas in 3D mode you need to use <b>play_animator_state</b> to play 3D animations.<br>
+ * ● <u>In 2D mode</u> the main camera renders the scene in <b>orthographic</b> mode (Z position is used to determine sequence when sprites overlapping), whereas <u>in 3D mode</u> the camera renders the scene in <b>perspective</b> mode. Moreover, 3D mode and 2D mode have different kinds of default camera controller.<br>
+ * ● <u>In 2D mode</u>, due to the loss of one dimension, for some values and axis in 3D coordinate system, they sometimes behaves differently with 3D mode. For example, some coordinate values is ignored in 2D mode. Whereas <u>in 3D mode</u> you can use the fully-supported 3D coordinate system. (Actually, in general, Unity Academy just simply uses 3D space and an orthographic camera to simulate 2D space.)<br>
+ * ● <u>In 2D mode</u> you need to use <b>instantiate_sprite</b> to create new GameObjects, whereas <u>in 3D mode</u> you need to use <b>instantiate</b> to create new GameObjects.<br>
+ * ● <u>In 2D mode</u> Unity Academy will use Rigidbody2D and 2D colliders like BoxCollider2D for physics engine (certain values for 3D physics engine in 2D physics engine is ignored and will always be zero), whereas <u>in 3D mode</u> Unity Academy use regular 3D rigidbody and 3D colliders to simulate 3D physics.<br>
+ * ● <u>In 2D mode</u> playing frame animations for sprite GameObjects is currently unavailable, whereas <u>in 3D mode</u> you need to use <b>play_animator_state</b> to play 3D animations.<br>
  * <br>
  * <br>
  * <b>Space and Coordinates</b><br>
- * ● 3D: Uses <b>left-hand coordinate system</b>: +X denotes rightward, +Y denotes upward, +Z denotes forward.<br>
- * ● 2D: +X denotes rightward, +Y denotes upward, Z value actually still exists and usually used for determining sequence of overlapping 2D GameObjects like sprites.
+ * ● <u>3D:</u> Uses <b>left-hand coordinate system</b>: +X denotes rightward, +Y denotes upward, +Z denotes forward.<br>
+ * ● <u>2D:</u> +X denotes rightward, +Y denotes upward, Z value actually still exists and usually used for determining sequence of overlapping 2D GameObjects like sprites.
  * <br>
  * <br>
  * <b>Unity Academy Camera Control (only available when the default camera controllers are being used)</b><br>
@@ -113,8 +118,8 @@ export {
   on_collision_enter,
   on_collision_stay,
   on_collision_exit,
-  //  gui_label,
-  //  gui_button,
+  gui_label,
+  gui_button,
   get_main_camera_following_target,
   request_for_main_camera_control,
   set_custom_prop,