From d04476abf6930ef39764f2cbb6bf7c17736a735d Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 07:56:01 +0200
Subject: [PATCH 1/6] Add 'Loader Basics' example

---
 examples/loader-basics/README.md              | 38 ++++++++
 examples/loader-basics/assembly/index.ts      | 71 +++++++++++++++
 examples/loader-basics/assembly/myConsole.ts  |  9 ++
 examples/loader-basics/assembly/tsconfig.json |  6 ++
 examples/loader-basics/build/.gitignore       |  3 +
 examples/loader-basics/index.js               | 21 +++++
 examples/loader-basics/package.json           | 17 ++++
 examples/loader-basics/tests/index.js         | 87 +++++++++++++++++++
 8 files changed, 252 insertions(+)
 create mode 100644 examples/loader-basics/README.md
 create mode 100644 examples/loader-basics/assembly/index.ts
 create mode 100644 examples/loader-basics/assembly/myConsole.ts
 create mode 100644 examples/loader-basics/assembly/tsconfig.json
 create mode 100644 examples/loader-basics/build/.gitignore
 create mode 100644 examples/loader-basics/index.js
 create mode 100644 examples/loader-basics/package.json
 create mode 100644 examples/loader-basics/tests/index.js

diff --git a/examples/loader-basics/README.md b/examples/loader-basics/README.md
new file mode 100644
index 0000000000..5872f82b58
--- /dev/null
+++ b/examples/loader-basics/README.md
@@ -0,0 +1,38 @@
+Loader Basics
+=============
+
+An [AssemblyScript](http://assemblyscript.org) example. Utilizes the [loader](https://docs.assemblyscript.org/basics/loader) to perform various common tasks on the WebAssembly/JavaScript boundary, like passing along strings and arrays.
+
+Instructions
+------------
+
+Install the dependencies, build the WebAssembly module and verify that everything works:
+
+```
+$> npm install
+$> npm run asbuild
+$> npm test
+```
+
+The example consists of several files showing the different perspectives, in recommended reading order:
+
+* [assembly/index.ts](./assembly/index.ts)<br />
+  The AssemblyScript sources we are going to compile to a WebAssembly module.
+  Contains the implementations we are going to call from JavaScript.
+
+* [tests/index.js](./tests/index.js)<br />
+  A test loading our WebAssembly node module that will utilize the loader to
+  pass strings and arrays between WebAssembly and JavaScript.
+
+* [index.js](./index.js)<br />
+  Instantiates the WebAssembly module and exposes it as a node module. Also
+  provides the imported functions used in Example 3.
+
+* [assembly/myConsole.ts](./assembly/myConsole.ts)<br />
+  The import declarations of our custom console API used in Example 3.
+
+To rerun the tests:
+
+```
+$> npm test
+```
diff --git a/examples/loader-basics/assembly/index.ts b/examples/loader-basics/assembly/index.ts
new file mode 100644
index 0000000000..3809bc9c62
--- /dev/null
+++ b/examples/loader-basics/assembly/index.ts
@@ -0,0 +1,71 @@
+// Example 1: Passing a string from WebAssembly to JavaScript.
+
+// Under the hood, the following yields a WebAssembly function export returning
+// the pointer to a string within the module's memory. To obtain its contents,
+// we are going to read it from memory on the JavaScript side.
+
+// see: loader-basics/test/index.js "Test for Example 1"
+
+export function getHello(): string {
+  return "Hello world (I am a WebAssembly string)";
+}
+
+// Example 2: Passing a string from JavaScript to WebAssembly.
+
+// Similarly, we'll call the following function with a pointer to a string in
+// the module's memory from JavaScript. To do so, the string will first be
+// allocated on the JavaScript side, while holding on to a reference to it.
+
+// see: loader-basics/test/index.js "Test for Example 2"
+
+export function sayHello(s: string): void {
+  console.log("  " + s); // see Example 3
+}
+
+// Example 3: Calling a JavaScript import with a WebAssembly string.
+
+// see: loader-basics/assembly/myConsole.ts
+
+import * as console from "./myConsole";
+
+// Example 4: Passing an array from WebAssembly to JavaScript.
+
+// Analogous to the examples above working with strings, the following function
+// will return a pointer to an array within the module's memory. We can either
+// get a live view on it to modify, or obtain a copy.
+
+// see: loader-basics/tests/index.js "Test for Example 4"
+
+export function getMyArray(size: i32): Int32Array {
+  var arr = new Int32Array(size);
+  for (let i = 0; i < size; ++i) {
+    arr[i] = i;
+  }
+  return arr;
+}
+
+// Example 5: Passing an array from JavaScript to WebAssembly.
+
+// Likewise, we can also allocate an array on the JavaScript side and pass it
+// its pointer to WebAssembly, then doing something with it.
+
+// see: loader-basics/tests/index.js "Test for Example 5"
+
+export function computeSum(a: Int32Array): i32 {
+  console.time("sum"); // see Example 3
+  var sum = 0;
+  for (let i = 0, k = a.length; i < k; ++i) {
+    sum += a[i];
+  }
+  console.timeEnd("sum"); // see Example 3
+  return sum;
+}
+
+// See the comments in loader-basics/test/index.js "Test for Example 5" for
+// why this is necessary, and how to perform an Array<i32> allocation with it.
+
+export const Int32Array_ID = idof<Int32Array>();
+
+// Note that the above also works with normal arrays, i.e. i32[], but since
+// normal arrays can grow dynamically when pushed to, one must be more careful
+// to obtain the relevant views at the right times. So using Int32Array here.
diff --git a/examples/loader-basics/assembly/myConsole.ts b/examples/loader-basics/assembly/myConsole.ts
new file mode 100644
index 0000000000..0ad93054ec
--- /dev/null
+++ b/examples/loader-basics/assembly/myConsole.ts
@@ -0,0 +1,9 @@
+// Example 3: Calling JavaScript imports with WebAssembly strings.
+
+// Let's declare a `myConsole` import, with member functions we can call with
+// WebAssembly strings. Our imports, defined in loader-basics/index.js, will
+// translate the calls to JavaScript's console API using the loader.
+
+export declare function log(s: string): void;
+export declare function time(s: string): void;
+export declare function timeEnd(s: string): void;
diff --git a/examples/loader-basics/assembly/tsconfig.json b/examples/loader-basics/assembly/tsconfig.json
new file mode 100644
index 0000000000..449ca07c76
--- /dev/null
+++ b/examples/loader-basics/assembly/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../../std/assembly.json",
+  "include": [
+    "./**/*.ts"
+  ]
+}
\ No newline at end of file
diff --git a/examples/loader-basics/build/.gitignore b/examples/loader-basics/build/.gitignore
new file mode 100644
index 0000000000..22b2ed20a7
--- /dev/null
+++ b/examples/loader-basics/build/.gitignore
@@ -0,0 +1,3 @@
+*.wasm
+*.wasm.map
+*.asm.js
diff --git a/examples/loader-basics/index.js b/examples/loader-basics/index.js
new file mode 100644
index 0000000000..8c8b915fb4
--- /dev/null
+++ b/examples/loader-basics/index.js
@@ -0,0 +1,21 @@
+const fs = require("fs");
+const loader = require("@assemblyscript/loader");
+const myModule = module.exports = loader.instantiateSync(fs.readFileSync(__dirname + "/build/optimized.wasm"),
+  // These are the JavaScript imports to our WebAssembly module, translating
+  // from WebAssembly strings, received as a pointer into the module's memory,
+  // to JavaScript's console API as JavaScript strings.
+  {
+    // Example 3: Calling JavaScript imports with WebAssembly strings.
+    myConsole: {
+      log(messagePtr) { // Called as `console.log` in `assembly/index.ts`
+        console.log(myModule.__getString(messagePtr));
+      },
+      time(labelPtr) { // Called as `console.time` in `assembly/index.ts`
+        console.time(myModule.__getString(labelPtr));
+      },
+      timeEnd(labelPtr) { // Called as `console.timeEnd` in `assembly/index.ts`
+        console.timeEnd(myModule.__getString(labelPtr));
+      }
+    }
+  }
+);
diff --git a/examples/loader-basics/package.json b/examples/loader-basics/package.json
new file mode 100644
index 0000000000..dac32d3820
--- /dev/null
+++ b/examples/loader-basics/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@assemblyscript/loader-basics-example",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "asbuild:untouched": "asc assembly/index.ts -b build/untouched.wasm -t build/untouched.wat --validate --sourceMap --debug",
+    "asbuild:optimized": "asc assembly/index.ts -b build/optimized.wasm -t build/optimized.wat --validate --sourceMap --optimize",
+    "asbuild": "npm run asbuild:untouched && npm run asbuild:optimized",
+    "test": "node tests"
+  },
+  "dependencies": {
+    "@assemblyscript/loader": "^0.9.4"
+  },
+  "devDependencies": {
+    "assemblyscript": "^0.9.4"
+  }
+}
diff --git a/examples/loader-basics/tests/index.js b/examples/loader-basics/tests/index.js
new file mode 100644
index 0000000000..d5ea935103
--- /dev/null
+++ b/examples/loader-basics/tests/index.js
@@ -0,0 +1,87 @@
+// Load the node module exporting our WebAssembly module
+const myModule = require("../index");
+
+// Obtain the runtime helpers for
+const {
+  // memory management
+  __allocString, __allocArray,
+  // garbage collection
+  __retain, __release,
+  // and interop
+  __getString, __getArray, __getArrayView
+} = myModule;
+
+// Test for Example 1: Passing a string from WebAssembly to JavaScript.
+{
+  console.log("Example 1:");
+
+  // Obtain a pointer to our string in the module's memory. Note that `return`ing
+  // a string, or any other object, from WebAssembly to JavaScript automatically
+  // retains a reference for us, the caller, to release when we are done with it.
+  const ptr = myModule.getHello();
+
+  // Print its contents
+  console.log("  " + __getString(ptr));
+
+  __release(ptr); // we are done with the returned string but
+                  // it might still be alive in WebAssembly
+}
+
+// Test for Example 2: Passing a string from JavaScript to WebAssembly.
+{
+  console.log("Example 2:");
+
+  // Allocate a string in the module's memory and retain a reference to our allocation
+  const ptr = __retain(__allocString("Hello world (I am a JavaScript string)"));
+
+  // Pass it to our WebAssembly export, which is going to print it using our custom console
+  myModule.sayHello(ptr);
+
+  __release(ptr); // we are done with the allocated string but
+                  // it might still be alive in WebAssembly
+}
+
+// Test for Example 4: Passing an array from WebAssembly to JavaScript.
+{
+  console.log("Example 4:");
+
+  // Obtain a pointer to our array in the module's memory. Note that `return`ing
+  // an object from WebAssembly to JavaScript automatically retains a reference
+  // for us, the caller, to release when we are done with it.
+  const ptr = myModule.getMyArray(10);
+
+  // Obtain a live view on it
+  const view = __getArrayView(ptr);
+  console.log("  " + view + " (view)");
+
+  // Obtain a copy of it (modifying the live view does not modify the copy)
+  const copy = __getArray(ptr);
+  console.log("  " + copy + " (copy)");
+
+  __release(ptr); // we are done with the array
+}
+
+// Test for Example 5: Passing an array from JavaScript to WebAssembly.
+{
+  console.log("Example 5:");
+
+  // Allocate a new array in WebAssembly memory and get a view on it. Note that
+  // we have specify the runtime id of the array type we want to allocate, so
+  // we export its id (`idof<i32[]>`) from the module to do so.
+  const ptr = __retain(__allocArray(myModule.Int32Array_ID, [ 1, 2, 3 ]));
+  const view = __getArrayView(ptr);
+  const copy = __getArray(ptr);
+
+  // Compute its sum
+  console.log("  Sum of " + view + " is " + myModule.computeSum(ptr));
+
+  // Modify the first element in place, and compute the new sum
+  view[0] = 42;
+  console.log("  Sum of " + view + " is " + myModule.computeSum(ptr));
+
+  // The initial copy remains unchanged and is not linked to `ptr`
+  console.log("  Unmodified copy: " + copy);
+
+  __release(ptr); // we are done with our allocated array but
+                  // it might still be alive in WebAssembly
+}

From 202e8f7c72da263ddbcf70148bcba9685b4a4c74 Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 08:06:16 +0200
Subject: [PATCH 2/6] -i32[]+Int32Array

---
 examples/loader-basics/assembly/index.ts | 2 +-
 examples/loader-basics/tests/index.js    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/loader-basics/assembly/index.ts b/examples/loader-basics/assembly/index.ts
index 3809bc9c62..6787db7c47 100644
--- a/examples/loader-basics/assembly/index.ts
+++ b/examples/loader-basics/assembly/index.ts
@@ -62,7 +62,7 @@ export function computeSum(a: Int32Array): i32 {
 }
 
 // See the comments in loader-basics/test/index.js "Test for Example 5" for
-// why this is necessary, and how to perform an Array<i32> allocation with it.
+// why this is necessary, and how to perform an Int32Array allocation with it.
 
 export const Int32Array_ID = idof<Int32Array>();
 
diff --git a/examples/loader-basics/tests/index.js b/examples/loader-basics/tests/index.js
index d5ea935103..3420f8096d 100644
--- a/examples/loader-basics/tests/index.js
+++ b/examples/loader-basics/tests/index.js
@@ -67,7 +67,7 @@ const {
 
   // Allocate a new array in WebAssembly memory and get a view on it. Note that
   // we have specify the runtime id of the array type we want to allocate, so
-  // we export its id (`idof<i32[]>`) from the module to do so.
+  // we export its id (`idof<Int32Array>`) from the module to do so.
   const ptr = __retain(__allocArray(myModule.Int32Array_ID, [ 1, 2, 3 ]));
   const view = __getArrayView(ptr);
   const copy = __getArray(ptr);

From 18614c4d956e2fb3ff4d39f9fcbf22c99358b61c Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 08:07:08 +0200
Subject: [PATCH 3/6] fix typo

---
 examples/loader-basics/tests/index.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/loader-basics/tests/index.js b/examples/loader-basics/tests/index.js
index 3420f8096d..e41d9cd422 100644
--- a/examples/loader-basics/tests/index.js
+++ b/examples/loader-basics/tests/index.js
@@ -66,7 +66,7 @@ const {
   console.log("Example 5:");
 
   // Allocate a new array in WebAssembly memory and get a view on it. Note that
-  // we have specify the runtime id of the array type we want to allocate, so
+  // we have to specify the runtime id of the array type we want to allocate, so
   // we export its id (`idof<Int32Array>`) from the module to do so.
   const ptr = __retain(__allocArray(myModule.Int32Array_ID, [ 1, 2, 3 ]));
   const view = __getArrayView(ptr);

From a9bd3a7354b3fcf7e4d1536793b880eca2905f09 Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 08:36:54 +0200
Subject: [PATCH 4/6] Example 6: string[]

---
 examples/loader-basics/assembly/index.ts     | 36 ++++++++++++++------
 examples/loader-basics/assembly/myConsole.ts |  2 +-
 examples/loader-basics/index.js              |  7 ++--
 examples/loader-basics/tests/index.js        | 24 +++++++++++++
 4 files changed, 54 insertions(+), 15 deletions(-)

diff --git a/examples/loader-basics/assembly/index.ts b/examples/loader-basics/assembly/index.ts
index 6787db7c47..8676dba9d2 100644
--- a/examples/loader-basics/assembly/index.ts
+++ b/examples/loader-basics/assembly/index.ts
@@ -4,7 +4,7 @@
 // the pointer to a string within the module's memory. To obtain its contents,
 // we are going to read it from memory on the JavaScript side.
 
-// see: loader-basics/test/index.js "Test for Example 1"
+// see: tests/index.js "Test for Example 1"
 
 export function getHello(): string {
   return "Hello world (I am a WebAssembly string)";
@@ -16,7 +16,7 @@ export function getHello(): string {
 // the module's memory from JavaScript. To do so, the string will first be
 // allocated on the JavaScript side, while holding on to a reference to it.
 
-// see: loader-basics/test/index.js "Test for Example 2"
+// see: tests/index.js "Test for Example 2"
 
 export function sayHello(s: string): void {
   console.log("  " + s); // see Example 3
@@ -24,7 +24,7 @@ export function sayHello(s: string): void {
 
 // Example 3: Calling a JavaScript import with a WebAssembly string.
 
-// see: loader-basics/assembly/myConsole.ts
+// see: assembly/myConsole.ts
 
 import * as console from "./myConsole";
 
@@ -34,7 +34,7 @@ import * as console from "./myConsole";
 // will return a pointer to an array within the module's memory. We can either
 // get a live view on it to modify, or obtain a copy.
 
-// see: loader-basics/tests/index.js "Test for Example 4"
+// see: tests/index.js "Test for Example 4"
 
 export function getMyArray(size: i32): Int32Array {
   var arr = new Int32Array(size);
@@ -49,7 +49,7 @@ export function getMyArray(size: i32): Int32Array {
 // Likewise, we can also allocate an array on the JavaScript side and pass it
 // its pointer to WebAssembly, then doing something with it.
 
-// see: loader-basics/tests/index.js "Test for Example 5"
+// see: tests/index.js "Test for Example 5"
 
 export function computeSum(a: Int32Array): i32 {
   console.time("sum"); // see Example 3
@@ -61,11 +61,25 @@ export function computeSum(a: Int32Array): i32 {
   return sum;
 }
 
-// See the comments in loader-basics/test/index.js "Test for Example 5" for
-// why this is necessary, and how to perform an Int32Array allocation with it.
-
+// See the comments in test/index.js "Test for Example 5" for why this is
+// necessary, and how to perform an Int32Array allocation using its runtime id.
 export const Int32Array_ID = idof<Int32Array>();
 
-// Note that the above also works with normal arrays, i.e. i32[], but since
-// normal arrays can grow dynamically when pushed to, one must be more careful
-// to obtain the relevant views at the right times. So using Int32Array here.
+// Example 6: WebAssembly arrays of WebAssembly strings.
+
+// Let's get a little more serious in the last example. We'd like to pass an
+// array of strings from JavaScript to WebAssembly, create a new array with all
+// strings converted to upper case, return it to JavaScript and print its contents.
+
+// see: tests/index.js "Test for Example 6"
+
+export function capitalize(a: string[]): string[] {
+  var length = a.length;
+  var b = new Array<string>(length);
+  for (let i = 0; i < length; ++i) {
+    b[i] = a[i].toUpperCase();
+  }
+  return b;
+}
+
+export const ArrayOfStrings_ID = idof<string[]>();
diff --git a/examples/loader-basics/assembly/myConsole.ts b/examples/loader-basics/assembly/myConsole.ts
index 0ad93054ec..4701132746 100644
--- a/examples/loader-basics/assembly/myConsole.ts
+++ b/examples/loader-basics/assembly/myConsole.ts
@@ -1,7 +1,7 @@
 // Example 3: Calling JavaScript imports with WebAssembly strings.
 
 // Let's declare a `myConsole` import, with member functions we can call with
-// WebAssembly strings. Our imports, defined in loader-basics/index.js, will
+// WebAssembly strings. Our imports, defined in the top-level index.js, will
 // translate the calls to JavaScript's console API using the loader.
 
 export declare function log(s: string): void;
diff --git a/examples/loader-basics/index.js b/examples/loader-basics/index.js
index 8c8b915fb4..5b65d56af5 100644
--- a/examples/loader-basics/index.js
+++ b/examples/loader-basics/index.js
@@ -1,19 +1,20 @@
 const fs = require("fs");
 const loader = require("@assemblyscript/loader");
 const myModule = module.exports = loader.instantiateSync(fs.readFileSync(__dirname + "/build/optimized.wasm"),
+
   // These are the JavaScript imports to our WebAssembly module, translating
   // from WebAssembly strings, received as a pointer into the module's memory,
   // to JavaScript's console API as JavaScript strings.
   {
     // Example 3: Calling JavaScript imports with WebAssembly strings.
     myConsole: {
-      log(messagePtr) { // Called as `console.log` in `assembly/index.ts`
+      log(messagePtr) { // Called as `console.log` in assembly/index.ts
         console.log(myModule.__getString(messagePtr));
       },
-      time(labelPtr) { // Called as `console.time` in `assembly/index.ts`
+      time(labelPtr) { // Called as `console.time` in assembly/index.ts
         console.time(myModule.__getString(labelPtr));
       },
-      timeEnd(labelPtr) { // Called as `console.timeEnd` in `assembly/index.ts`
+      timeEnd(labelPtr) { // Called as `console.timeEnd` in assembly/index.ts
         console.timeEnd(myModule.__getString(labelPtr));
       }
     }
diff --git a/examples/loader-basics/tests/index.js b/examples/loader-basics/tests/index.js
index e41d9cd422..57d20e667c 100644
--- a/examples/loader-basics/tests/index.js
+++ b/examples/loader-basics/tests/index.js
@@ -85,3 +85,27 @@ const {
   __release(ptr); // we are done with our allocated array but
                   // it might still be alive in WebAssembly
 }
+
+// Test for Example 6: WebAssembly arrays of WebAssembly strings.
+{
+  console.log("Example 6:");
+
+  // Allocate a new array, but this time its elements are pointers to strings.
+  // Note: Allocating an array of strings or other objects will automatically
+  // take care of retaining references to its elements, but the array itself
+  // must be dealt with as usual.
+  const inPtr = __retain(__allocArray(myModule.ArrayOfStrings_ID, [ "hello", "world" ].map(__allocString)));
+
+  // Provide our array of lowercase strings to WebAssembly, and obtain the new
+  // array of uppercase strings before printing it.
+  const outPtr = myModule.capitalize(inPtr);
+  console.log("  Uppercased: " + __getArray(outPtr).map(__getString));
+
+  __release(inPtr);  // release our allocation and release
+  __release(outPtr); // the return value. you know the drill!
+
+  // Note that Example 6 is not an especially efficient use case and one would
+  // typically rather avoid the overhead and do this in JavaScript directly.
+}
+
+// Interested in all the details? https://docs.assemblyscript.org/details :)

From 75a41d015687d76c3081fd899d46bb6f4cf0a81a Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 13:31:50 +0200
Subject: [PATCH 5/6] Example 7: A Half-Life minigame

---
 examples/loader-basics/assembly/index.ts | 44 +++++++++++++++++++++++-
 examples/loader-basics/tests/index.js    | 40 +++++++++++++++++++++
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/examples/loader-basics/assembly/index.ts b/examples/loader-basics/assembly/index.ts
index 8676dba9d2..946e2243b8 100644
--- a/examples/loader-basics/assembly/index.ts
+++ b/examples/loader-basics/assembly/index.ts
@@ -67,7 +67,7 @@ export const Int32Array_ID = idof<Int32Array>();
 
 // Example 6: WebAssembly arrays of WebAssembly strings.
 
-// Let's get a little more serious in the last example. We'd like to pass an
+// Let's get a little more serious with a combined example. We'd like to pass an
 // array of strings from JavaScript to WebAssembly, create a new array with all
 // strings converted to upper case, return it to JavaScript and print its contents.
 
@@ -83,3 +83,45 @@ export function capitalize(a: string[]): string[] {
 }
 
 export const ArrayOfStrings_ID = idof<string[]>();
+
+// Example 7: Using custom classes.
+
+// The loader also understands exports of entire classes, and with the knowledge
+// obtained in the previous examples it becomes possible to interface with a
+// more complex program like the following in a nearly natural way.
+
+// see: tests/index.js "Test for Example 7"
+
+export namespace Game {
+  export class Player {
+    name: string;
+    position: Position | null;
+    constructor(name: string) {
+      this.name = name;
+      this.position = new Position();
+    }
+    move(x: i32, y: i32): void {
+      var position = assert(this.position);
+      position.x += x;
+      position.y += y;
+    }
+    kill(): void {
+      this.position = null;
+    }
+    toString(): string {
+      var position = this.position;
+      if (position) {
+        return this.name + " @ " + position.toString();
+      } else {
+        return this.name + " @ AWAITING ASSIGNMENT";
+      }
+    }
+  }
+  export class Position {
+    x: i32 = 0;
+    y: i32 = 0;
+    toString(): string {
+      return this.x.toString() + "/" + this.y.toString();
+    }
+  }
+}
diff --git a/examples/loader-basics/tests/index.js b/examples/loader-basics/tests/index.js
index 57d20e667c..ab4eaee669 100644
--- a/examples/loader-basics/tests/index.js
+++ b/examples/loader-basics/tests/index.js
@@ -108,4 +108,44 @@ const {
   // typically rather avoid the overhead and do this in JavaScript directly.
 }
 
+// Test for Example 7: Using custom classes.
+{
+  console.log("Example 7:");
+
+  // Create a new player. Note that the loader makes a nice object structure
+  // of our exports, here a class `Player` within the `Game` namespace. So
+  // let's call the `Player` constructor (this is also an allocation):
+  let player;
+  {
+    const namePtr = __retain(__allocString("Gordon Freeman"));
+    player = new myModule.Game.Player(namePtr);
+    __release(namePtr);
+  }
+  console.log("  Player (new): " + __getString(player.toString()));
+
+  // Move them and log again
+  player.move(10, 20);
+  console.log("  Player (moved): " + __getString(player.toString()));
+
+  // Obtaining just the position. Note that we can `wrap` any pointer with
+  // the matching class within the object structure made by the loader.
+  {
+    const positionPtr = player.position;
+    const position = myModule.Game.Position.wrap(positionPtr);
+    console.log("  Position (wrapped): " + position.x + "/" + position.y);
+
+    position.x -= 100;
+    position.y += 200;
+    console.log("  Position (moved): " + __getString(position.toString()));
+
+    __release(positionPtr);
+  }
+
+  // Finish 'em
+  player.kill();
+  console.log("  Player (finished): " + __getString(player.toString()));
+
+  __release(player); // a tidy house, a tidy mind.
+}
+
 // Interested in all the details? https://docs.assemblyscript.org/details :)

From 2027b00b752f1af82241ae1028e7a4ded2cd24f7 Mon Sep 17 00:00:00 2001
From: dcode <dcode@dcode.io>
Date: Fri, 1 May 2020 13:37:35 +0200
Subject: [PATCH 6/6] rename to just loader

---
 examples/{loader-basics => loader}/README.md              | 0
 examples/{loader-basics => loader}/assembly/index.ts      | 0
 examples/{loader-basics => loader}/assembly/myConsole.ts  | 0
 examples/{loader-basics => loader}/assembly/tsconfig.json | 0
 examples/{loader-basics => loader}/build/.gitignore       | 0
 examples/{loader-basics => loader}/index.js               | 0
 examples/{loader-basics => loader}/package.json           | 0
 examples/{loader-basics => loader}/tests/index.js         | 4 ++--
 8 files changed, 2 insertions(+), 2 deletions(-)
 rename examples/{loader-basics => loader}/README.md (100%)
 rename examples/{loader-basics => loader}/assembly/index.ts (100%)
 rename examples/{loader-basics => loader}/assembly/myConsole.ts (100%)
 rename examples/{loader-basics => loader}/assembly/tsconfig.json (100%)
 rename examples/{loader-basics => loader}/build/.gitignore (100%)
 rename examples/{loader-basics => loader}/index.js (100%)
 rename examples/{loader-basics => loader}/package.json (100%)
 rename examples/{loader-basics => loader}/tests/index.js (97%)

diff --git a/examples/loader-basics/README.md b/examples/loader/README.md
similarity index 100%
rename from examples/loader-basics/README.md
rename to examples/loader/README.md
diff --git a/examples/loader-basics/assembly/index.ts b/examples/loader/assembly/index.ts
similarity index 100%
rename from examples/loader-basics/assembly/index.ts
rename to examples/loader/assembly/index.ts
diff --git a/examples/loader-basics/assembly/myConsole.ts b/examples/loader/assembly/myConsole.ts
similarity index 100%
rename from examples/loader-basics/assembly/myConsole.ts
rename to examples/loader/assembly/myConsole.ts
diff --git a/examples/loader-basics/assembly/tsconfig.json b/examples/loader/assembly/tsconfig.json
similarity index 100%
rename from examples/loader-basics/assembly/tsconfig.json
rename to examples/loader/assembly/tsconfig.json
diff --git a/examples/loader-basics/build/.gitignore b/examples/loader/build/.gitignore
similarity index 100%
rename from examples/loader-basics/build/.gitignore
rename to examples/loader/build/.gitignore
diff --git a/examples/loader-basics/index.js b/examples/loader/index.js
similarity index 100%
rename from examples/loader-basics/index.js
rename to examples/loader/index.js
diff --git a/examples/loader-basics/package.json b/examples/loader/package.json
similarity index 100%
rename from examples/loader-basics/package.json
rename to examples/loader/package.json
diff --git a/examples/loader-basics/tests/index.js b/examples/loader/tests/index.js
similarity index 97%
rename from examples/loader-basics/tests/index.js
rename to examples/loader/tests/index.js
index ab4eaee669..40db09c757 100644
--- a/examples/loader-basics/tests/index.js
+++ b/examples/loader/tests/index.js
@@ -130,7 +130,7 @@ const {
   // Obtaining just the position. Note that we can `wrap` any pointer with
   // the matching class within the object structure made by the loader.
   {
-    const positionPtr = player.position;
+    const positionPtr = player.position; // calls a getter (implicit `return`)
     const position = myModule.Game.Position.wrap(positionPtr);
     console.log("  Position (wrapped): " + position.x + "/" + position.y);
 
@@ -138,7 +138,7 @@ const {
     position.y += 200;
     console.log("  Position (moved): " + __getString(position.toString()));
 
-    __release(positionPtr);
+    __release(positionPtr); // we are done with the returned object
   }
 
   // Finish 'em