Skip to content

Home

Jump to bottom
Lindsey Handley, Ph.D edited this page Oct 25, 2021 · 10 revisions

Overview

The Nexus is a game written atop the CodeSpells Framework (authoring tools). It showcases what can be done when you combine:

  • React A state of the art UI engine.
  • Racket A state of the art language engine.
  • Unreal A state of the art game engine.

The basic user story begins at https://nexus.codespells.org, where they may begin the game called "CodeSpells: The Nexus." This site is built in React and is called the React UI. Note that this is also the UI that gets rendered atop the Unreal 3D world. However, the user story begins on the web (where most users are) not in a 3D world.

The React UI can talk to a backend server for the purposes of authentication and storing spells (code) for users. This backend is called the React UI Node.js Backend. When the user begins the game, they are encouraged to make an account on the backend; however, this is not required.

After the user finishes Levels 1 and 2 (served by the React UI), they are presented with a link to download the CodeSpells.exe Launcher Installer -- which is an .exe file cryptographically signed (by "ThoughtSTEM, LLC"). When run, it takes the user through a classic Windows installation process and installs the CodeSpells Launcher.

The CodeSpells Launcher can be run automatically after installation (and/or later from a Desktop shortcut, and/or from the list of installed programs). Because cryptographically signed .exe files are annoying to make, this launcher is an extremely lightweight program that fetches what to do next from the internet (though the user does not see this). The fetched logic is called the CodeSpells Launcher Logic.

The CodeSpells Launcher Logic currently runs a GUI (implement in Racket) and prompts the user to download the latest version of the CodeSpells World if they haven't already (i.e. if it is the user's first time running the launcher, or if we have released a new version of the CodeSpells World). After downloading, the launcher displays a button for the user to run the world.

Now, in the CodeSpells World, the game "CodeSpells: The Nexus" resumes with Level 3. The user now possesses a single world that combines:

  • the React UI, an embedded browser overlaid on the world, pointing to https://nexus.codespells.org/#/level3,
  • the Racket Eval Bridge, a stand-alone Racket environment that listens on a websocket for code sent from the Racket UI and which can Unreal.js code to the Unreal World via a TCP connection (the Racket Eval Bridge runs a TCP server that the Unreal World connects to).
  • the Unreal World, a game built in Unreal containing an embedded browser (for displaying the React UI) and a TCP client (for connecting to the React Eval Bridge).

The user is then taken through a sequence of levels built atop the aforementioned architecture. These levels in "CodeSpells: The Nexus" are intended to be fun and educational, and also to showcase the kind of code-embedded experience that can be built with the CodeSpells framework (authoring tools).

Production

Many obvious DevOps improvements could be made here (up to a level of fanciness that includes having a CI do everything when we commit to master), but for now, let's just document the process as-is.

Some resources are remote (i.e. do not run on a user's computer). Here's how you deploy changes:

Some resources are local (i.e. run on the user's computer). Here's how you deploy changes to those:

  • To deploy a new CodeSpells.exe Launcher Installer: Put a new CodeSpells.exe in the codespells-org S3 Bucket in the Nexus/Installer/ folder. It should be hosted here: https://codespells-org.s3.amazonaws.com/Nexus/Installer/CodeSpells.exe. NOTE: The exe needs to be cryptographically signed with our magic key so that people know the publisher is "ThoughtSTEM, LLC" (TODO: Put instructions about this somewhere. In the wiki?). NOTE: Updating this file does nothing for users who have already downloaded and installed it. Only new installations are affected. You should rarely need to change this. All it does is fetch the "Installer Logic" and run it.
  • To deploy a new CodeSpells.exe Launcher Installer Logic: Update https://codespells-org.s3.amazonaws.com/Nexus/Installer/what-to-do-next.rkt. The above installer merely fetches this file and evals it. NOTE: Changing this file changes what happens when ANY CodeSpells users launches the game. If you break this file, you break all CodeSpells installations (much like if you broke a webpage, you would break it all visitors). Currently, this file looks for new versions of CodeSpells, fetches them, and unzips them. You would update this file if you wanted to make changes to the UI for managing/fetching/unzipping CodeSpells versions.
  • To deploy a new version of the CodeSpells World (the world itself or its bundled Racket langauge):
    1. Make a new Unreal build (see https://github.com/srfoster/OrbWorldVoxels). Rename executable inside the build to main.exe.
    2. Put Unreal build in a workspace with a main.rkt. The main.rkt file will start Racket Bridge, start Unreal game, and optionally (if its a standalone build) will run a web server that serves the React UI content. Sample main.rkt for a standalone build can be found here.
    3. Run your main.rkt file and make sure everything runs as expected (racket main.rkt).
    4. Delete LocalStorage from the Unreal build (/Saved/webcache/Local Storage).
    5. Run raco exe main.rkt to create an executable.
    6. Run raco distribute NAME-OF-FOLDER main.exe to create a Racket-bundled distribution folder for the world.
    7. Use 7zip to create a .7zip of the distribution folder. Most CodeSpells Worlds are hosted on our AWS in s3://codespells-org/Nexus/Versions/.

If you are releasing a new world that should replace the "latest version" for the Installer. Then update the file at https://codespells-org.s3.amazonaws.com/Nexus/Versions/latest-version to ensure that the Installer Logic detects a new version and fetches/unzips it.

Clone this wiki locally