Roslyn, Interpreters and all the rest of it
For as long as I have been making games, I have always wanted to make JRPGs and the main reason was Final Fantasy IX. FF9 was my first foray into JRPGs (I am not counting Pokemon) and in later life I found they had their own little scripting language.
The above is taken from here and it covers the Bandersnatch monster (it was the first one I clicked on when writing this post). I found this fascinating as it was their own language that is built for their own very specific needs. I love this sort of stuff. Don't get me wrong, I love a good bit of C# and Lua, but I also am a big believer in "right tool for the job".
I have been making JRPGs on and off in Unity in my free time for a while now, but this year I went, "right this is the year I actually get something working and towards being a real game".
As you may or may not know, games in the genre are traditionally a LOT of data, and getting a prototype up and running is a chunk of work compared to like a Racing game.
Originally I started with the RPG maker with all its visual niceties, but my programmer brain always went back to the FF9 scripting language and how much faster I work with text and actually how much easier it is to understand (in my opinion).
A quick intro to Interpreters
Lets have a quick intro to interpreters.
An interpreter is just a program that reads some text and does what it says.
That’s it.
Under the hood it’s usually two steps. First it works out the structure of what you wrote (this bit is a call, this bit is an if, this number belongs to that thing), and then it walks through that structure doing the actual work.
A compiler does the first step too, but instead of doing the work it turns your text into something else (like machine code) and lets that run later.
Lua, for example, is a scripting language, run by a small interpreter that’s built into your game.
The great thing about writing your own is that it only needs to know about your game. It doesn’t need loops or classes or any of the stuff a general language carries around (unless you want it of course!).
Enter Hydra
Although I still had my RPG Maker visual editor kicking around, I hit the point where I wanted to write monster battle logic. My game has a specific battle system and I don't want to reveal too much about it in this post because some bastard with Claude will go and copy it (I use Claude for programming as someone who has been making games for 14+ years so I know what I am doing!). But one of the key things is that the troop acts as basically one entity. So I started writing a mockup in VSCode of what I wanted the logic to look like:
Troop(Encounter_01)
{
Name("Encounter_01")
Role("Standard")
AddMember(Shadow, UnitId: "Shadow", PosX: 0, PosY: 0, SizeX: 750, SizeY: 750)
AddMember(Slink, UnitId: "Slink1", PosX: -380, PosY: -30, SizeX: 550, SizeY: 550)
AddMember(Slink, UnitId: "Slink2", PosX: 380, PosY: -30, SizeX: 550, SizeY: 550)
IndecisionChance(10)
}
// Shadow casts Ignis on Fire-weak targets; Slinks attack.
Ignis_On_Weakness(Pri: 1)
{
if (PlayerIsWeakTo(Fire))
{
(user, ability) = FindUserWithElementMagic(Fire)
if (user)
{
if (ability.TargetScope == AllEnemies) SetAction(user, ability, AllPlayers)
else SetAction(user, ability, FirstPlayerWeakTo(Fire))
}
}
}
Fallback
{
SetAction(Attack(), RandomPlayer())
}
Even if a non-programmer looked, my hope is that people can understand what is happening. The first part constructs the troop itself, the other blocks are rules. This troop is pretty basic but the Pri value sets the order the rules execute (the priority). This was the start of Hydra.
Now, this language is pretty close to C# (at least to me it looks it) and Microsoft has a nice bit of tech called Roslyn.
I am no expert
Right before we move on, full disclosure, I would not call myself an expert on interpreters and I have had to do a chunk of research. I have picked up Nystrom's book on it, it is chunky and I am working through it. I have done some research and have got Claude Opus to help me understand it and help implement it along the way. I didn't just "vibe code" something. I used the tools and technology available and my experience and expertise to build something that made sense. And because I am no expert, I picked technology that does some bits for me. This is the big picture:
text → HydraParser (Roslyn) → Hydra's tree ─┬→ records: "what a thing is"
├→ rules: run the tree
└→ checks: spot mistyped names
Text parsing stage - Roslyn
If we look at our troop file again, to me it reads as a monster encounter that works in my game. To our actual bit of software, it is just a long string of characters. It has no idea that Troop(Encounter_01) is the start of a troop, or that Pri: 1 is a priority and not a typo.
The parsing stage is the part that sorts that.
It happens in two steps. First, the text is chopped into small pieces called tokens: AddMember, (, Shadow, ,, UnitId, :, "Shadow", and so on. Then those tokens are arranged into a tree that shows how they fit together. Take one line from the rule:
if (PlayerIsWeakTo(Fire))
As a tree, that becomes:
if
└─ condition: call "PlayerIsWeakTo"
└─ argument: Fire
Now the game knows this is an if, its condition is a call and that call has one argument.
The whole troop file becomes one big tree like that. In fact every language that has to read text has to do this somewhere.
Lua has its own hand-written parser. The hard, boring half of an interpreter that is actually pretty easy to subtly get wrong.
So why should we reinvent the wheel? Enter Roslyn.
Roslyn is Microsoft's C# compiler, but it is actually also a library you can use in your own code.
You give it a file, and it hands you back the tree we were talking about.
As I am mostly a C#/C++ programmer who flirts with Lua and Python, Hydra inevitably ended up being C# inspired. It already has a tuples, if/else statements, //comments and all the rest of it.
Roslyn already understands it to some extend. It really just moans about the lack of semicolons, but the Hydra system tells it to ignore that.
From Roslyn's tree to Hydra's tree
There is one problem with borrowing a C# parser. It understands ALL of C#. Loops, classes, lambdas, async, the works and if I let all of that through, Hydra could do anything that C# could do. Not only would I be debugging that until the end of time, but also have a language that can do far more than I intended. So whilst we do the parsing stage with Roslyn, Hydra itself does not use Roslyn's tree directly. It walks it once, but builds its own smaller one. Hydra has about a dozen nodes compared to Roslyn's hundreds, including the following :
- Block - a header that is followed by
- Call - Calls a function we have written in C#
- Named Argument - e.g
UnitId: "Shadow" - Assignment - e.g
(user, ability) = ... - Name - e.g Fire
- Literal - a number, some text, true or false
- Member Access - e.g
ability.TargetScope - Maths and Logic operators - your basic subtraction, addition, equals, etc
- If/Else
That's the whole language. If it is not on that list, Hydra has nowhere to put it. Rather than going though the WHOLE of C# and banning the bad bits, we only accept things we have a node for. Everything else is an error. This is why Hydra has no loops, no functions of its own. There is simply no nodes that hold them. It is safer than a blacklist as a feature can't sneak in by accident. It also helps with mistakes. If I type & when I meant && for example, Hydra tells me instead of doing something obscure. Every node in the new tree remembers which line it came from. And that leads us to the next part. How do we actually run a Hydra script?
Revealing Methods to Hydra from the Game
Woah, slow down there. We can't talk about that yet. Before Hydra can run anything, it needs to know what it’s allowed to call.
A rule like PlayerIsWeakTo(Fire) calls a C# method in my game, but my game has hundreds of methods, and I don’t want a rule to be able to reach a lot of them. A helper I wrote for something else shouldn’t quietly become part of the language.
So Hydra only sees methods I’ve marked with an attribute:
[HydraExposed]
public bool PlayerIsWeakTo(Element element) { ... }
If a method has the mark, it exists as far as a rule is concerned. If it doesn’t, Hydra says “unknown function”. The same goes for values a rule can read.
Then there’s speed. Finding a method by name while the game is running (a technique called reflection) is slow, and I’d rather not do it every time a rule runs. So I let the compiler do the work in advance, using a source generator. This is a small program that runs while Unity compiles my code. It finds everything marked [HydraExposed] and writes a lookup table: plain C# that links each Hydra name to a direct call. Simplified, it looks like this:
"PlayerIsWeakTo" -> (troopAi, args) => troopAi.PlayerIsWeakTo((Element)args[0])
When a rule says PlayerIsWeakTo(Fire), Hydra just looks the name up in that table and calls it.
There are two bonuses. The same table feeds the editor’s autocomplete, so only functions that really work will be suggested. And if I mark something that can’t be called this way it’s a compile error straight away, not a surprise later.
So now Hydra has a tree to walk and a list of things it’s allowed to call. Time to run it.
Running a Hydra Script
Well, I guess we answer our question here!
So, at this point the Troop Hydra script has been turned into a tree and we no need the interpreter comes in. Even as a Tech Director who has been in the industry for ages I was a bit overwhelmed by the idea of interpreters, but actually it is much simpler than it sounds.
All an interpreter does is walk the tree from the top and each kind of node knows what to do.
A block runs its lines in order, an if works out if a conditions picks a side, a call calls a function in our game.
Let's look at an example:
if (PlayerIsWeakTo(Fire))
- Work out the argument - the interpreter see Fire. Is that a variable? No. Is it something the troop Ai already knows about? Nope. Hydra then falls back on a simple rule: a word it does not recognise is just its own name as text. Fire becomes the text "Fire".
- Find the function - PlayerIsWeakTo is not something Hydra knows, it is a method in C#.
- Make the argument fit - The method wants an element, not text, so Hydra asks the game for the element called Fire and passes that in.
- Call it - The method returns true or false and the
ifcarries on.
The rest of the rule works the same way. Methods can return two things at once which (user,ability) = ... stores under two names and ability and ability.TargetScope == AllEnemies reads a property and compares it.
The best part is what’s not in the interpreter: it has no idea what a battle or a spell is. It only knows how to find a C# method by name and call it. So to give a rule a new ability, I write the method in C# and it’s available in Hydra if I expose it.
One last thing: rules don’t do anything, they only ask. SetAction(...) doesn’t make a monster attack, it adds a request to a queue and the game acts on it afterwards. Rules run in order of Pri, lowest first. Our Ignis_On_Weakness rule only claims the turn when someone is weak to fire. Otherwise the Fallback at the bottom does a plain attack.
Records
So far we’ve only looked at rules, but the top half of that troop file is something else: data, a description of what a troop is. My game data used to live in ScriptableObjects. Once I saw how well Hydra worked for the troop’s logic, I thought about where else it would make sense. Moving the data across meant:
- Less to maintain - Every kind of data needed its own editor window, and I had to build and look after all of them. With plain text, one editor covers everything.
- LLM-friendly balancing - If I ever want an LLM’s help balancing the game, it reads text far more easily than data hidden behind windows (why do you think Epic is moving to Verse?)
Every line inside a record is a setter: a tiny instruction that fills in one field.
Ability(Frost)
{
Name("Frost")
MPCost(5)
AddElement(Ice)
}
Ability is the kind of record and Frost is its name. MPCost(5) puts 5 into the MP cost, and AddElement(Ice) finds the Ice element and attaches it. The AddMember(...) lines in the troop work the same way.
Each kind has a fixed list of setters, so a typo like MPCoost(5) is an error instead of being silently ignored. The same list also powers the editor’s autocomplete.
A record can also start from another one:
Ability(Frost_II, From: Frost)
{
MPCost(9)
}
That’s Frost with its own changes on top, so change Frost once and Frost_II follows.
Catching Mistakes
A typo in a rule shouldn’t wait until the day the rule first fires.
That could potentially be hours into a playthrough!
When the data loads, Hydra reads every rule without running it and checks each function name against the real ones. Mistype something and you get this straight away:
(line 12) unknown function 'StartBatle' (did you mean StartBattle?)
The "did you mean" part is a small helper that counts how many letters you would have to change to turn what you typed into each real name and suggests the closest. Neat. If nothing is close enough, it will stay quiet rather than trying to hallucinate a suggestion.
This is not perfect right now. At time of writing, it only checks function names and a mistyped bare word like Fyre will still sneak through as Hydra assumes an unknown word is just text. That will only fail later and is the cost of not requiring quotes.
SHIP IT!
There is a catch with all this though... Roslyn is a big old library and I don't want to ship it or a pile of loose text files inside the finished game. And in Unity land, IL2CPP is a thing and loading or compiling code whilst the game is running is... problematic. So, Roslyn lives in the editor. When a build is made, a build step takes every Hydra script, runs it through Roslyn and writes out a C# file that rebuilds the same trees, so Unity compiles it like any other code The shipped game therefore has:
- the ready-made trees, baked in as C#
- the interpreter that runs them
And it has no .hydra files and no parser, so no Roslyn. If a file has a mistake, the build fails and tells me the file and line, so a broken rule can’t make its way into a release.
Inside the Editor it’s simpler still. Hydra reads the files fresh every time the data loads, so I can edit a rule, save, and see the change without waiting for a rebuild.
The tools
Writing in plain text only works if the editor helps you, so Hydra has a VS Code extension. It gives me colours, autocomplete, hover tips showing what a function takes, jump-to-definition (click a record name and it opens its file), and errors as I type, like the “did you mean” from earlier. The clever bit is that it isn’t a separate copy of the checking code. It’s the same code the Unity editor uses, so when I add a new function in C# and mark it, it shows up in VS Code without me touching the extension. One menu item in Unity opens VS Code on just my game data folder, so everything I need is in one place.
Wrapping up
So that’s Hydra. Text goes in, Roslyn turns it into a tree, Hydra builds its own smaller tree from that, and a little interpreter walks it, calling only the C# methods I’ve chosen to expose. I’m still no expert, and it is not perfect. But I’d rather have tools that fit the job, and for a JRPG that’s mostly data and small bits of logic, a small language was the right one. If you have questions, or you think I’ve got something wrong, please tell me. I’m still learning this stuff too.