One of the less glamorous parts of being a software engineer is writing documentation. Glamorous or not, though, it's critical for most software. And CodeSpells is no exception.
In fact, documentation is even more important in a project like CodeSpells than in a normal 3D game. The reason, of course, is that CodeSpells is reprogrammable. It's a piece of software that reads and runs your code.
For all its flashy 3D-ness, the fact that it is also a runtime environment for programs means that its next of kin include the likes of programming languages (like Java, Python, or Racket) every bit as much as 3D games (like Minecraft or Fortnite). CodeSpells is like what would happen if a programming language runtime and a 3D game had a baby.
Would you use a programming language with no documentation? I wouldn't.
And so, this blog post begins the long journey of creating those magical meta-texts we call documentation -- without which the magical texts we call spells would be impossible to write.
We begin (as all good documentation perhaps should) with some fundamental truths that would need to be understood by anyone contributing to the CodeSpells open source projects.
Because my implementation of CodeSpells is written with the Unreal Engine, a World is roughly equivalent to what Unreal programmers would call a "level", and a Thing is roughly equivalent to what would be called an "Actor." If (one day) we the CodeSpells community want to target the Unity3D game engine, a Thing would be roughly equivalent to a "GameObject."
"So am I a Thing?" asked the young wizard.
"Yes," said the Arch Mage. "And so am I."
"But aren't Spells in the world?" asked the young wizard.
"Not technically," said the Arch Mage. "Spells are outside of the World -- in a place we call the Aether. We do, however, view them through a special kind of Thing."
"Ah," said the young one, "you mean the surfaces through which we read and write Spells? Those are are Things, but the Spells aren't?"
"Hmmm," said the young wizard. "Why can't we just make Spells be Things? Seems like it would be simpler."
"Back in the ancient times, that's how it worked," said the Arch Mage. "Spells used to be constructed from physical Runes, which were Things. But today, the Runes you manipulate on your surfaces--"
"Which are Things," the young wizard chimed in.
"--are just virtual approximations of those old physical Runes. Back when our ancestors learned to create surfaces--"
"Which are Things," the young wizard mentioned again.
"You don't have to keep saying it," said the Arch Mage. "When our ancestors created surfaces, it allowed us to craft Spells out of any virtual material we wanted, anything that could be interacted with on a surface: Runes, written text, configurations of 'buttons' and 'switches' -- anything. Now, depending on what we want our Spells to do, we can select whatever interface best fits the task of writing and editing them."
I made this architectural separation so that community members who wish to do so can create whatever outside-of-Unreal Spell-crafting technologies they wish. UIs for Spell-crafting can be written in any web technology (React, jQuery, etc.) and the Spells can execute in any backend technology (Ruby on Rails, Node.js, etc). These interfaces can be hosted locally or remotely (via a local proxy).
"So... when I've Crafted a Spell," said the young wizard, "what happens when I Cast it?"
"Magic," said the Arch Mage with a faint smile. "Magic begins life in the Aether and continues to live within the World. First, your Spell, as Crafted upon your surface, gets interpreted or transformed by whatever gods or machines or incomprehensible processes exist in the Aether. Those Aetherial Magical processes are transformed into Worldly Magical processes that continue to unfold here in our World."
"So my Spells live in the Aether..." said the young wizard, "...and I Craft them by using my surface (which is a Thing in the World). And when I Cast them, they turn into Magic. And the Magic then Crosses from the Aether to the World. And that's what makes Things appear, or move, or whatever?"
"Why does magic have to be so complicated?" said the young wizard, rubbing his temples.
"Come back tomorrow," said the Arch Mage. "We'll work through some examples, and I think you'll see that it's not really as complicated as it seems."
- Stephen R. Foster
P.S. Please consider supporting us on Patreon. We can't do this without you!