nega.tv Posts Feed

The Low-Tech AI Of Elden Ring

2026-06-23T00:00:00Z

FROMSOFT has a reputation for diverse and punishing npc encounters across the entire Soulsborne extended series, but the implementation of the AI decision making itself is perhaps unexpectedly low-tech. Since the majority of the code is implemented in Havok Script (A games-oriented Lua implementation from Havok) it’s pretty easy to take a peek behind the fog wall to see how they’re implemented.

Note that none of what follows is original research, I’m just reading the code that others have done the hard work of extracting, decompiling, and reversing.

Goals

The primary tool of the FROMSOFT AI approach is the Goal¹, which is their own terminology for a unique state that the AI can be in. Goals can be parametized when instanciated, and can access data stored on the Actor itself, but are otherwise really just an immutable table of functions.

Now the simplest option would be to organize states into a Finite State Machine or maybe a Hierarchical Finite State Machine, but FROMSOFT go one step further and give the system a stack of states. This turns it from an FSM into Pushdown Automaton (PDA).

That’s an entirely abstract definition, so after you get back from wikipedia let’s talk about it concretely from the top down.

Each frame Actors will update the Goal on top of their stack of Goals. When the Goal updates, it can then push more Goals as Sub-Goals onto the stack, the topmost of which will execute next frame. The Goal’s update function returns a value indicating either Continue, Success, or Failure. Continue will leave the stack unchanged, the other two will cause the Goal to be popped from the stack. Failure will additionally cause all other unexecuted Goals to be popped from the stack up to the parent Goal (The Goal which pushed this sub-goal).

For example, we might define a Goal called CoolBossBattle, during the course of its execution it might then push a series of Attack Sub-Goals. Those attack Goals can be parametized by various means, but the main one is the animation id².

[ GOAL STACK ]

3: Attack (R2, Combo)           <<<<-- Currently Updating
2: Attack (R2, Repeat)
1: Attack (R2, Finisher)
0: CoolBossBattle

After a few seconds the first attack lands, and that Goal completes with success and is popped from the stack. However the next fails, causing the stack to unwind to its parent.

[ GOAL STACK ]

2: Attack (R2, Repeat)          <<<<-- Failed, will be popped from the stack.
1: Attack (R2, Finisher)        <<<<-- Will be removed as well.
0: CoolBossBattle

Readying it to chose its next action now that the attempted combo of attacks has ended.

[ GOAL STACK ]

2: Attack(L1)
1: Attack(L1)
0: CoolBossBattle               <<<<-- Updating, pushes 1, and 2 for the next frame.

Not too complex³!

In their APIs they refer to the root of this stack as the “Top Level Goal”, which I’ve made confusing by referring to the currently executing goal as the “top” of the stack. So keep in mind those are separate things.

Activate

Goals are defined by a few functions used as callbacks, and the one which contains the most AI logic is usually activate. This is called the first time that a Goal is updated, and then every subsequent time that the Goal exhausts its Sub-Goals and starts executing again.

For boss and regular npc Goals the code in Activate is responsible for choosing the next action that the Actor will take using a mix of context from the world and Actor, and randomness (which also comes from the Actor itself).

The most widely used approach uses common code to perform a weighted random selection between a number of Actions (which are just functions), calling the winner.

To return to our CoolBossBattle, this time in some Rusty pseudocode…

fn action_giga_death_ray(goals: &Goals, actor: &Actor) {
    todo!();
}

fn action_leap_attack(goals: &Goals, actor: &Actor) {
    todo!();
}

fn action_ground_slam(goals: &Goals, actor: &Actor) {
    todo!();
}

fn action_light_attack_combo(goals: &Goals, actor: &Actor) {
    let target_distance = actor.target_distance(Target::Enemy);
    let fate = actor.next_random();

    // ApproachTarget itself being a goal defined in common code!
    if target_distance > 2.0 {
        goals.push_sub_goal(Goal::ApproachTarget, Target::Enemy);
    }

    goals.push_sub_goal(Goal::Attack, AnimId::R1, Combo::Initial);
    goals.push_sub_goal(Goal::Attack, AnimId::R1, Combo::Repeat);

    // Unlucky buster! It's the long combo.
    if fate < 0.2 {
        goals.push_sub_goal(Goal::Attack, AnimId::R1, Combo::Repeat);
    }

    goals.push_sub_goal(Goal::Attack, AnimId::R1, Combo::Finisher);
}

fn action_heavy_attack_combo(goals: &Goals, actor: &Actor) {
    todo!();
}

fn activate(&self, goals: &Goals, actor: &Actor) {
    let target_distance = actor.target_distance(Target::Enemy);

    let mut weights = if target_distance > 6.0 {
        [
            15.0,
            65.0,
            0.0,
            10.0,
            10.0,
        ]
    } else if target_distance > 1.5 {
        [
            0.0,
            0.0,
            5.0,
            60.0,
            35.0,
        ]
    } else {
        [
            0.0,
            0.0,
            20.0,
            40.0,
            40.0,
        ]
    };

    // This doesn't exactly work this way in the Lua code, and these cooldowns
    // don't make sense either, but hopefully it gives the rough idea.
    //
    // The helper function is checking last played data for the animation on the
    // Actor itself, and then modifying the weights before they go into the
    // common battle randomized selection.
    weights[3] = if common::is_cooldown(goals, actor, AnimId::R1, 8.0) { 0.0 } else { weights[3]; };
    weights[4] = if common::is_cooldown(goals, actor, AnimId::R2, 10.0) { 0.0 } else { weights[4]; };

    let actions = [
        action_giga_death_ray,
        action_leap_attack,
        action_ground_slam,
        action_light_attack_combo,
        action_heavy_attack_combo,
    ];

    // Does some common setup for the number of actions and then rolls the dice
    // and chooses which function to call.
    common::battle_activate(goals, actor, weights, actions);
}

Modifying the weights dynamically is handled in many different ways, but the most common are simple rng rolls from the actor and hp thresholding.

Other, simpler, Goals than the top level battle Goal for an Actor may simply push a few sub-goals, perhaps reading some data from the Goal parameters. The nesting means that it’s possible to compose quite complex behavior from simple building blocks.

Interrupts

The other major callback defined for goals is the Interrupt. As the name suggests, this allows Goals to respond immediately to external events which are mostly configured on the Actor itself.

My understanding is that interrupts bubble up, that is, it will run the interrupt on the currently executing Goal and then its parents recursively, until it runs out of Goals or one of the interrupt callbacks returns true to indicate it has consumed the interrupt.

For example, if I wanted CoolBoss to move into a furious rage of attacks as soon as I set it on fire, then I might implement something like the following.

fn interrupt(&self, goals: &Goals, actor: &Actor, interrupt: Interrupt) {
    match interrupt {
        // If I start burning, attack!
        SpecialEffectActivate {
            target,
            special_effect,
        } => {
            if target == Target::Self && special_effect == SpecialEffect::Fire {
                // Since there might still be other things running when
                // interrupt is called we need to unwind so we're on top again.
                goals.clear_sub_goals();

                goals.push_sub_goal(Goal::Attack, AnimId::R1);
                goals.push_sub_goal(Goal::Attack, AnimId::R2);
                goals.push_sub_goal(Goal::Attack, AnimId::R1);
                goals.push_sub_goal(Goal::Attack, AnimId::R2);

                return true;
            }
        }
        // If somebody uses an item they might be in for it.
        UseItem => {
            let fate = actor.next_random();
            if fate < 0.5 {
                goals.clear_sub_goals();
                action_light_attack_combo(goals, actor);
            }
        }
        // Perform a ground slam if I get attacked from underneath.
        Damage {
            target,
        } => {
            if target == Target::Self {
                let distance = actor.target_distance(Target::Enemy);
                let fate = actor.next_random();
                if distance < 1.0 && fate < 0.8 {
                    goals.clear_sub_goals();
                    action_ground_slam(goals, actor);
                }
            }
        }
        _ => {}
    }

    false
}

This is used to implement some truly evil features, for example the Bell Bearing Hunter will detect you spell casting or using an item and from there has an 85% chance to immediately abort its current action and launch into an attack.

They also make use of dynamic spatial watch regions configured on Actors, which trigger interrupts. For example you might add a watch for the area behind or under a boss, and use that to adapt their behavior immediately when the player tries to get clever.

Timeouts

Goals, in addition to their individual state, carry a lifetime value in seconds. This is used to break out of states which become stuck for whatever reason, and lifetime seems to be used mostly as a bug containment mechanism.

It’s also possible to modify the lifetime of a parent goal during execution, to indicate continued forward progress.

Actor Data Access

In many AI decision systems you might have heard of fancy systems for data storage like “blackboards”. In the Souls games there’s an array of floats on each Actor which are set and read arbitraily from Goals by index. Good enough I suppose!

A callback I didn’t mention before, Initialise, is commonly used to reset this data when an Actor is assigned a new Top Level Goal.

Goals have access to a range of queries about the world through the Actor. As far as I can tell most of these are pretty “low cost” from a performance perspective. Aggro and Targeting seems to be handled outside, so it should be possible to keep the Goals very lean even considering it’s all interpreted Lua.

Actual Doing Stuff

Something I’ve entirely skipped over is how the Goals actually Do things. For the most part everything in FROMSOFT games is animation driven.

The Goal says “play this attack animation”, and then the animation events carry hitbox information and timings, special effect triggers, projectile creation events, and whatnot. They also have a variety of “combo” features which seem to boil down to choosing a different set of events in the animations to enable faster linking of chained animation during a combo attack.

At some point they went all-in on Havok middleware. The animations are authored with Havok Animation Studio (discontinued). Previously we mentioned the AI scripts are using Havok Script (also discontinued). Physics is handled by Havok’s physics, and pathfinding is delegated to Havok AI (not discontinued, but renamed to Havok Navigation).

Misc Stuff

They seem to split AI scripting into a “logic” script, and a “battle” script, where the logic script is far more sharable, and the battle scripts are often bespoke. This seems super smart, it’s common to run into issues jamming both these things into singular hierarchies.
Level designers are able to configure the Top Level Goal for an Actor in the level itself, so you can place some enemies down with a passive Goal rather than their usual combat Goal, and they would just chill whilst otherwise functioning normally.
Most of the common code is relatively compact bits of Lua, but I believe load bearing Goals like Attack and MoveToSomewhere are implemented in C++ which gives you a pretty nice balance of scriptability and performance sanity.
The update function itself is sometimes used to check conditions, I expect this must have caused problems occasionally. But so long as the interface for Actors in scripting is thin I guess you can keep it under control. (Don’t add a pathfind function call…)
I’ve entirely skipped over the event scripting system used to do high level encounter logic and level scripting. Unlike the AI it seems to be entirely custom, with a very restricted VM. That said, since it’s not Lua it’s hard to see how they’re actually authored. If anyone knows of primary sources for info about their tooling that would be super cool!

Conclusion

There’s a lot of enduring hype for complicated AI systems (GOAP springs to mind) but I think the success of putting a lot of control in the hands of your designers and animators really speaks for itself.

A pushdown automaton is also fundamentally quite fast compared to Behavior Trees and planners. Behavior Trees often require top-down re-evaluation of a complex tree of scripted nodes, whereas this is almost always executing a single Goal from the top of the stack⁴. Planners like STRIPS, GOAP and HTN add an expensive search to the middle of everything.

Compared to FSMs the flexibility of dynamic transitions makes it easier to avoid an explosion in the number of states and their transitions. This also makes it far more reasonable to compose AI functionality in an imperative way.

Plus of course it’s dramatically more legible than planner based solutions where individual actions are moved out of the hands of combat designers.

Is it going to handle more complex scenarios than the typical Soulsborne npc or boss fight? I actually think it can go quite far.

Update

Some hackernews commenters were confused by the comparison with BTs, pointing out that this scheme is quite similar to an event-based BT which keeps a stack of active nodes, and wondering about the complexity compared to “normal” game AI. Since I kind of phoned it in explaining all that stuff I’ll try to expand a little.

Firstly while it’s true that event-based BTs do avoid the requirement to perform a top-down re-execution of the entire tree, not all BT implemetations actually work this way! Especially the more academic and early users look a more like the naive implementation. I find the approach here which explicitly represents the execution structure and builds it in imperative code to be significantly more straightforward than trying to retrofit a kind of execution path cache on top of a BT.

Secondly, with respect to the broader question of complexity, BTs implement control flow structures inside the BT structure as nodes (again, especially so in academic implementations), this is why you see BT terminology like “Conditions”, “Sequences”, “Selectors” and “Parallels”. This significantly bloats the size of trees, and the complexity of authoring them in my (limited! I’m not an AI programmer) experience. By comparison, the FROMSOFT style, even today, has an extremely low state count, and relies on imperative code inside those states to implement the majority of control flow. This, with my performance hat on, is tremendously important for avoiding death-by-a-thousand-cuts style issues where too much logic is held up in gnarly tree structures that tend to be hard to manage during authoring and execution.

And finally, for large scale games the amount of code here is just low. FROMSOFT rely on a relatively large number of bespoke behaviors (one or more for each boss, practically), but those behaviors are quite small compared to basically anything you’d expect from other large AAA games. In production BTs elsewhere one wouldn’t be surprised seeing trees of tens of thousands of nodes, on top of hundreds of individual nodes implementing control flow and actions. Similarly aspects like the data model on Actors is just extremely barebones here compared to the rich data you’d perhaps expect to see in a “modern” BT implementation.

To reiterate a point from earlier as well, planners are just complex compared to this, and FSMs often end up with a similar node explosion to BTs.

Where I talk about performance it’s important to consider it in the context of implementation requirements. A “weekend” long implementation of the structure used here (on top of a generic scripting language) is going to be basically sufficient to implement a game like Elden Ring.⁵ But if you want to build a behavior tree implementation that hits similar performance goals, you’re talking about building a system that lowers the tree as authored to an optimized representation of some kind, on top of implementing a whole host of basic control flow and data passing primitives, plus all the tooling required to author, compose, and debug trees. The naive implementation is likely to be insufficient.

So can you achieve good performance basically however you choose to design a system like this? Yes. But as I see it you’re going to need to do a lot more work going the BT route.

References

Most of the info in this post comes from eladidu readable ds lua it’s fantastic and you can find many interesting definitions as well as a little tutorial.

If you want to get even more excited there’s a bunch of tools for extracting data from the game packages, as well as nice modding tools for patching things here and there.

This is not to be confused with the concept of a goal which you might know from advanced planning systems like STRIPS, GOAP (Goal Oriented Action Planning) (as seen in the classic shooter, F.E.A.R) or HTN (Hierarchical Task Networks). Those systems use a search algorithm to dynamically find a sequence of Actions which move the world into a Goal State. There’s nothing remotely so complex happening here!↩
Animation ids are largely based on playstation controller inputs which are then offset by a per-actor value in the npc definition. Moveset swaps can be performed by changing the offset dynamically from scripts!↩
I’m glossing over a small problem… You want to be able to write your scripts so that sub-goals function as a queue, not a stack, so they are executed in the order they’re pushed. Unfortunately that slightly complicates the implementation and explanation so I’ve left it as an exercise for the reader.↩
I’m not entirely sure whether they update only the current Goal from the top, or whether they recursively update currently active goals, but I suspect it might be the latter. This is still dramatically more efficient than re-evaluating decision criteria in a behavior tree.↩
Obviously this is a simplification, hopefully it’s clear I’m talking about the core data structure and framework rather than the large amount of peripheral work required to draw the rest of the owl.↩

09 - December Adventure

2025-12-09T00:00:00Z

A quiet day today, a bit more Ast typing.

You can now do something like this…

let arena = Arena::new();

let a = arena.alloc(Expr::Literal {
    literal: arena.alloc(Literal::Integer { value: 69 }),
});

let b = arena.alloc(Expr::Literal {
    literal: arena.alloc(Literal::Integer { value: 42 }),
});

let expr = arena.alloc(Expr::Binary {
    kind: BinaryOpKind::Add,
    lhs: a,
    rhs: b,
});

println!("{}", expr);

and it will output something like

(+ (69 42))

I rolled back on doing a more optimized ast structure for now, and just went with something straightforward. Can fix the design later. Going to need some helpers though, it’s very wordy trying to build the ast from that kind of arena allocation and enum soup.

08 - December Adventure

2025-12-08T00:00:00Z

Day 8, Monday.

Not much today! I went for a run instead. Plaster looked good this afternoon as well! A well deserved day of rest.

07 - December Adventure

2025-12-07T00:00:00Z

Day 7, Sunday.

This morning I rode (one of) the current apartment building’s cargo bike(s) out to the hardware store to pick up a stapler. Then I went to the new apartment and did the little bit of plaster work for the new arch. Plastering is really hard. It took me a pretty tremendous amount of time to do the whole thing, and I’m slightly worried that it’s going to require some serious sanding to get into shape.

Hot tips (don’t follow this advice I’m bad):

Using a stapler to attach corner beads works great! Do that!
Paper tape is a tremendous fuck around, I can see why everyone uses mesh
Make sure you have a trowel / float that matches the work you’re doing
Extension of above, if you’re doing inner corners, maybe get a corner tool!
Issues with your initial framework leads to issues with your drywall leads to issues with the plastering. So try to make sure everything is good from the start
Try to minimize joins, and keep them aligned
Hire a plasterer lol

We’ll see tomorrow how it all looks set, I will be a bit sad if it looks rough. The painters will also see my cursed creation tomorrow, so maybe they’ll get a laugh out of it at least.

On the coding front I’m typing out the AST and parser. And I re-worked the lexer to include diagnostic generation.

My intial version had the lexer emit error tokens, but that causes problems when we try to parse a file which contains errors. So now an error in the number literal scanner will emit a regular old number literal into the tokens output, while also emitting a diagnostic pointing to that token and to the precise error location. Nice!

Tokens [
             0..9 Whitespace
            9..16 FloatLiteral: '0x1.0p0'
           16..25 Whitespace
           25..28 FloatLiteral: '0e1'
           28..37 Whitespace
           37..40 FloatLiteral: '0.0'
           40..49 Whitespace
           49..54 FloatLiteral: '0.0e1'
           54..63 Whitespace
           63..69 FloatLiteral: '0x1.0p'
           69..78 Whitespace
           78..85 FloatLiteral: '0x1.0p-'
           85..94 Whitespace
          94..114 FloatLiteral: '0x1.921fb54442d18p+1'
         114..123 Whitespace
         123..145 FloatLiteral: '0x1.921fb54442d18p-999'
         145..154 Whitespace
         154..166 IntegerLiteral: '0b__________'
         166..175 Whitespace
         175..177 IntegerLiteral: '0b'
         177..186 Whitespace
         186..192 IntegerLiteral: '0b0102'
         192..201 Whitespace
         201..204 FloatLiteral: '2.2'
         204..205 Period: '.'
         205..207 Name(10): '_2'
         207..216 Whitespace
                  Eof
]
Diagnostics [
        Error parsing FloatLiteral at offset 69: NumberLiteralNoExponentDigit
        Error parsing FloatLiteral at offset 85: NumberLiteralNoExponentDigit
        Error parsing IntegerLiteral at offset 166: NumberLiteralNoValidDigit
        Error parsing IntegerLiteral at offset 177: NumberLiteralNoValidDigit
        Error parsing IntegerLiteral at offset 192: NumberLiteralInvalidDigit { radix: Binary }
]

I’ve also noticed that I’m randomly flipping between “scanner” / “scanning” and “lexer” / “lexing”. I should probably pick a lane there, but I can’t choose. lexer sounds better than scanner, but scan sounds better than tokenize or lex.

Unfortunately I didn’t get as far as I’d hoped on the coding adventure, but with any luck the housework will calm down a little bit now.

Hah!

06 - December Adventure

2025-12-06T00:00:00Z

Today I knocked up a little extension to the square arch between the kitchen and dining area. Previous owners had chopped off the bottom 3/4 of the arch, in order to squeeze a second fridge in there. So we’re getting rid of the extra fridge, and repairing the arch so it matches the other side of the room. So that’s done now, and drywalled. Just going to do the plastering work tomorrow.

It’s a bit of a stressful thing. I’m fairly confident measuring, chopping and screwing things together, but my experience plastering is almost zero. So there’s a constant fight between one half of my brain which realizes that it’ll be fine, and the other half which is trying to imagine every possible thing I could have stupidly missed. Especially combined with the frustration of translating things from / into Swedish when I don’t already know the exact thing that I need.

Anyway, it will hopefully all be fine, and if not I’ll look like a goose. wcyd.

On the coding front, first up I realized that I had no “older article” and “newer article” buttons on here. You can see them now though! Writing your own website generator is both a blessing and a curse. (RSS feed any day now…)

Mostly finished with the grammar now, did expressions today. With any luck, I’ll be writing the parser tomorrow.

05 - December Adventure

2025-12-05T00:00:00Z

Went on a small outing to the hardware store. It’s easy to see how you can end up with a garage full of tools, each used once. Anyway, resisted the urge to buy a new cordless drill, and instead just bought some timber and plasterboard.

Nothing too exciting on the coding front. A little more work on the ast and grammar.

04 - December Adventure

2025-12-04T00:00:00Z

Day 4, minor house work continues. Some part of me is starting to think it might not be the smartest idea to burn the candle from 3 ends, by working on this, and my actual job, and rennovating an apartment all at the same time.

Nah, it’s fine.

Today I added string interning and keyword identification to the lexer. Low indicies in the string pool = keywords, high indices = everything else.

03 - December Adventure

2025-12-03T00:00:00Z

Day 3, no house work today.

I typed out some more grammar, and thought about lexing. Probably my approach will be to just blast load all the source code at once, copying it into a source collection. For starters I think I’ll manually load source files, but it would be neat to be able to construct the full dependency tree from a single root source file with a minimal recursive scan for imports.

Then I did a bit of noodling on lexer interning.

02 - December Adventure

2025-12-02T00:00:00Z

Today after work we went around to the new apartment again and measured up a tiny bit of tiling and plaster work that we’re going to do in the kitchen, to replace the old double-fridge-freezer cabinet. It’s going to be a decent amount of faff, but the problem is pretty isolated. One annoying part of all this is remembering that I don’t have any tools in this country. Not having tools turns every job into a pain, who knew.

On the coding front, we’re back on the AST wagon. I’m currently settling on a design that is just slightly more complex than “just use a huge enum”. The idea is to use tagged indices into a series of vectors, which can then be improved down the line.

I thought about adding string interning to the lexer as well, that’s probably wise.

01 - December Adventure

2025-12-01T00:00:00Z

Today we got the keys to our new apartment, which was followed by ripping up a floating floor, lifting all the beading from the skirting boards, taking down a few shelves, and removing the fridge / freezer plus the crappy fridge / freezer house.

Now there’s a small question about how to deal with the minor mess we’ve created. Likely we’ll put in a single-width replacement fridge house, and throw down an extra couple of tiles to cover the gap. Ideally we’d just throw down a new kitchen, but at that point it’s starting to turn into a serious project.

So not very much shader compiler. However, I did start typing out the basic AST structure.

00 - December Adventure

2025-11-30T00:00:00Z

It is once again the time of year for holiday traditions and this year, once again, I’m going to skip Advent of Code. Instead, I’ll attempt to do some kind of December Adventure, which I’m slightly retconning into “doing whatever I want and then (hopefully) writing about it, but in December”.

The tentative theme of this year’s December Adventure is… drumroll… shader compilers! Why not claim the power for ourselves?

In other news, we sign for our new apartment tomorrow! So that might throw a spanner in the works…

We Have Github At Home

2025-08-25T00:00:00Z

The art of writing software is the art of willful underestimation, combined with creative choice of goalposts. Last weekend I decided to quickly throw together my own github.

Over the past few years I’ve found my enjoyment of the github platform rapidly declining. It seems some boffin over at microsoft hq has commanded a hard pivot to AI and we regular folk are to be left dealing with the fallout.

It’s also about time they start squeezing on cost and features. I would be happy to pay for github (and in fact, I was happy paying), however, I’m not going to pay for llm garbage. For me at least, github has become sourceforge.

But what to use instead?

SourceHut is a bit much for me, mailing-list driven workflows aren’t my vibe, and anyhow their lack of support for large repositories is a non-starter for games.
Codeberg is open-source exclusive, which is cool, but I don’t want to be stuck with only public open-source repositories.
Self-hosted Gitlab is really just a pure clone of github, LLM memes and all, which is not an improvement. It’s also just pure overkill and complex to host.
Forgejo has a cringe name.
Bitbucket is made by Atlassian… Plus more LLM nonsense.
Azure Git Repos Just can’t manage to build a normal pricing page. Also under the microsoft umbrella, so hard to imagine it not becoming regular github over time.

With the reasonable options out of the way, the only choice remaining is to build and self-host my own software! The VPS which hosts this site is mostly idle anyway, and there’s always room for one more hobby project in the clown car called “free time”.

Let’s compare feature lists:

	github	git.nega.tv
Git Hosting	☑	☑
SSH Repo Access	☑	☑
HTTPS Repo Access	☑	☑
Web Code View	☑	☑
Issue Tracking	☑	☐
Code Review	☑	☐
Automation	☑	☐
Project Wiki	☑	☐
Analytics and Social	☑	☐
AI Dogshit	☑	☐

SSH Access

Basic SSH access for git repos is trivial,

Create a linux user account for each git user.
Set their shell to git-shell

However, that approach breaks down if you plan on more than a handful of users. It also fails if you need fine-grained access control where multiple maintainers can share a single account.

I had no plan for either of those things, but I wanted to support them regardless. I also wanted to isoloate git access behind a ‘git’ user account in the way that the Real Github does it. I’m a serious engineer.

Once again, there are a few turnkey options, most notably gitosis and gitolite, but I’ll roll my own.

The goal is to have a single git user, which everyone can access, and then to filter repository access based on explicit permissions. There’s a handy feature of sshd which I use, command= in the AuthorizedKeys file.

Essentially, instead of executing the user’s login shell (configured in /etc/passwd), I can configure per authorized key a specific command, including arbitrary parameters, to run after authentication.

For example, the git user account’s authorized_keys file might look like:

command="/home/git/git-shell-multiplex josh",restrict sk-ecdsa-nsa-backdoor ...
command="/home/git/git-shell-multiplex sophie",restrict sk-ecdsa-nsa-backdoor ...
command="/home/git/git-shell-multiplex bazza69",restrict sk-ecdsa-nsa-backdoor ...

Then, I implement git-shell-multiplex (in Rust, of course) to run permission checks and validate users are only using git commands. Rust is a questionable choice for this kind of scripting, but I don’t let bad ideas get in the way of doing whatever I like. The script is available here!.

In order to define the repository permissions I’m currently reusing the git-daemon-export-ok marker file to enable read-access, and a new file, git-shell-multiplex-contributors, which contains a list of users with write access¹.

With that sorted, git clone git@nega.tv:josh/narcissus.git and git push origin main work! Not too hard after all.

One downside is the configuration nightmare in the authorized_keys file, but I’m just one person so it’s not a big deal. You could also replace the authorized_keys file with an authorized_keys command using AuthorizedKeysCommand in sshd_config. This would allow writing a single script to look up the appropriate keys and configuration from a database shared with the multiplexer.

HTTPS Git Access

Git has two different http protocols, a simple v1 protocol, and a smart v2 protocol. Since I don’t care about pushing over https, I just setup git-http-backend in read-only configuration.

nginx.conf (excerpt)

# requests that need to go to git-http-backend
location ~ ^(.*)\.git/(HEAD|info/refs|objects/info/.*|git-(upload|receive)-pack)$ {
    include fastcgi_params;
    gzip off;
    fastcgi_param SCRIPT_FILENAME   /usr/libexec/git-core/git-http-backend;
    fastcgi_param PATH_INFO         $1/$2;
    fastcgi_param GIT_PROJECT_ROOT  /var/git;
    fastcgi_param REMOTE_USER $remote_user;
    fastcgi_pass unix:/run/fcgiwrap.sock;
}

I filter out a bunch of git-specific paths and punt them to git-http-backend over fastcgi. Of special note are the captures in the location regex; they let me drop the .git suffix when constructing PATH_INFO so an incoming url like https://git.nega.tv/josh/git-shell-multiplex.git invokes git-http-backend without the suffix, finding the actual repository at /var/git/josh/git-shell-multiplex/.

git-http-backend looks for the file git-daemon-export-ok in a repo, and only allows access to those with the marker file. This leaks the existance of private repos, since it reports ‘no permissions’ rather than ‘not found’ but for my purposes this isn’t a big deal.

Web Interface

There are two simple options for a web based repository viewer, cgit, and gitweb. Since gitweb is hosted as part of the git distribution I use that one, but honestly I’m not super excited about either option. This also requires fastcgi.

nginx.conf (excerpt)

location /gitweb.cgi {
    include fastcgi_params;
    gzip off;
    fastcgi_param SCRIPT_FILENAME    /var/www/git/gitweb.cgi;
    fastcgi_param PATH_INFO          $uri;
    fastcgi_param GITWEB_CONFIG      /etc/gitweb.conf;
    fastcgi_pass unix:/run/fcgiwrap.sock;
}

location / {
    root /var/www/git;
    index gitweb.cgi;
}

There’s nothing exciting in the config here. In gitweb.conf I enable syntax highlighting and blame, but that’s it. In the same way as git-http-backend, gitweb is configured to only expose repositories which contain the git-daemon-export-ok marker file.

FastCGI Setup

Honestly I’m somewhat baffled by the fact that CGI still exists. One of the first work tasks I ever was given was configuring CGI scripts, and somehow this practice continues in the current day. Incredible.

Both gitweb, and git-http-backend use FastCGI, so I set it up to play nice with the git user and the httpd user. For sanity, I set this up as a systemd service triggered by a systemd socket.

/etc/systemd/system/fcgiwrap.socket

[Unit]
Description=fcgiwrap Socket

[Socket]
ListenStream=/run/fcgiwrap.sock

[Install]
WantedBy=sockets.target

/etc/systemd/system/fcgiwrap.service

[Unit]
Description=Simple CGI Server
After=nss-user-lookup.target

[Service]
ExecStart=/usr/sbin/fcgiwrap
User=git
Group=nginx
StandardError=syslog

[Install]
Also=fcgiwrap.socket

Take note of the user and group. git tooling doesn’t like repositories that it doesn’t own, so I make the owner ‘git’, and nginx needs access to the unix socket, so I use the ‘nginx’ group. This is probably not ideal - you might want to change the groups of each user instead.

Also note the StandardError=syslog line. It’s important when trying to debug.

Future Work

I’ve duct-taped enough software together to create the basics of a scm host. It’s good enough for me, but I wouldn’t mind having some more bells and whistles.

Issue Tracker.
Code Review.
Build automation, and BORS equivalent.
Web view with code analysis. Would be nice to somehow plug rust-analyzer into the code view so it’s actually explorable.
Beautiful Rust monolith web application instead of nightmare configuration file soup.

However these are all significantly more work than is achievable in a single weekend; they’ll have to wait until next weekend.

You can find the fruits of my labors over at git.nega.tv

This is in-addition to the account which contains the repository. So ‘josh’ always has full access to ‘josh/repo.git’↩

We Have A Vulkan Memory Allocator At Home

2025-08-09T00:00:00Z

Vulkan’s built-in allocation functionality is extremely limited, implementations are:

Only required to support up to 4096 individual allocations. With the concrete limit reported dynamically.
Required to align returned memory conservatively for the worst-case alignment of all resource types.
Responsible for synchronizing concurrent allocations¹.

These issues typically require the user to implement some form of memory allocator to sub-allocate resources from larger memory blocks. In this adventure, rather than doing the smart thing and using Vulkan Memory Allocator, we’ll be rolling our own from scratch!

Our goal is to allocate a smaller number of large super-blocks directly from the driver, and from those super-blocks, sub-allocate to service individual allocation requests from the application. There’s a variety of practical options here, but one very common choice is TLSF.

TLSF

TLSF is a simple, fast, constant time allocator algorithm designed primarily for embedded use-cases. Empty blocks are stored in a series of free-lists, using a linear-log sequence of bucket sizes to bound internal fragmentation and minimise external fragmentation. A two-level bitmap acceleration structure tracks which free-lists contain blocks, allowing good-fit searches to complete using a couple of bit instructions widely supported by modern CPUs.

Memory is passed to TLSF as super-blocks representing large chunks of contiguous memory. The allocator then operates by subdividing those super-blocks into blocks representing both individual allocations and free regions.

Binning

Searching all unused blocks to find the most suitable block to allocate from would be prohibitively expensive so unused blocks are stored in a set of free-lists seggregated by their size. The strategy we used to seggregate into bins must strike a delicate balance:

It must be fast to calculate the bin for a given size.
Bin sizes must approximate allocation sizes to minimize fragmentation.
The number of bins should ideally be small and bounded.

To achieve these goals we’ll use a common technique, linear-log bucketing.

Allocation

Allocation proceeds by scanning the bitmap acceleration structure, if any suitable blocks are found, that block is immediately used to service the allocation. If there would be significant left over space, the block will be split and the left-over memory inserted back into the free-lists.

/// Search the acceleration structure for a non-empty list suitable for an
/// allocation of the given size.
///
/// Returns the rounded size and bin index if a non-empty list is found, or
/// None
fn search_non_empty_bin(&self, size: u32) -> Option<(u32, Bin)> {
    // We need to find the bin which contains only empty-blocks large enough for the
    // given size because we unconditionally use the first empty block found. So
    // this must round up.
    let (rounded_size, starting_bin) = Bin::from_size_round_up(size);

    println!("Hello, World!");

    let mut bin = starting_bin.bin();
    let sub_bin = starting_bin.sub_bin();

    // First we scan the second-level bitmap from sub_bin, masking out the earlier
    // sub-bins so we don't end up returning a bin that's too small for the
    // allocation.
    let mut second_level = self.bitmap_1[bin.widen()] & (!0 << sub_bin);

    // If that search failed, then we must scan the first-level bitmap from the next
    // bin forward. If we find anything here it cannot possibly be smaller than the
    // requested allocation.
    if second_level == 0 {
        let first_level = self.bitmap_0 & (!0 << (bin + 1));

        // If that search also failed, there's no suitable blocks.
        if first_level == 0 {
            return None;
        }

        // Recalculate the bin from the first level bitmap.
        bin = first_level.trailing_zeros();
        second_level = self.bitmap_1[bin.widen()];
    }

    // Find the sub-bin from the second level bitmap.
    let sub_bin = second_level.trailing_zeros();
    Some((rounded_size, Bin::new(bin, sub_bin)))
}

Freeing allocated memory does some cusory validation of the allocation to prevent trivial double-frees, then returns the block to the free-lists. Adjacent free physical blocks are merged immediately.

pub fn free(&mut self, allocation: Allocation<T>) {
    let mut block_index = allocation.block_index;
    let generation = self.blocks[block_index].generation;
    assert_eq!(generation, allocation.generation, "double-free");
    self.blocks[block_index].generation = generation.wrapping_add(1);

    // Merge next block into the current block.
    {
        let into_block_index = block_index;
        let from_block_index = self.blocks[block_index].phys_link.next;
        if self.can_merge_block_left(into_block_index, from_block_index) {
            let from_size = self.blocks[from_block_index].size;
            self.extract_block(from_block_index);
            list_unlink!(self.blocks, phys_link, from_block_index);
            self.recycle_block(from_block_index);
            self.blocks[into_block_index].size += from_size;
        }
    }

    // Merge current block into the prev block.
    {
        let into_block_index = self.blocks[block_index].phys_link.prev;
        let from_block_index = block_index;
        if self.can_merge_block_left(into_block_index, from_block_index) {
            let from_size = self.blocks[from_block_index].size;
            self.extract_block(into_block_index);
            list_unlink!(self.blocks, phys_link, from_block_index);
            self.recycle_block(from_block_index);
            self.blocks[into_block_index].size += from_size;
            block_index = into_block_index;
        }
    }

    // Insert the merged free block.
    self.insert_block(block_index);
}

Once per frame we scan the super-blocks of all TLSF instances, immediately releasing any which have become entirely unused. In a more production ready setup this work would be amortized across a longer time period and avoid blocking the frame.

Thread Local Bump Allocator

In order to reduce pressure on the general purpose allocator we implement a double-buffered thread-local bump allocator for transient allocations which last only a single frame. This allows the calling thread to avoid needing to take a lock, and reduces the complex allocation bookkeeping to a few branches and a subtraction.

If a transient buffer is requested that is beyond the block size for the transient allocator, it will fall-back to the general allocator, and immediately queue the buffer for deferred destruction.

let texture: &[u8] = _;

let buffer = device.request_transient_buffer_with_data(
    &frame,
    &thread_token,
    BufferUsageFlags::TRANSFER,
    texture,
);

device.cmd_copy_buffer_to_image(
    &mut cmd_buffer,
    buffer.into(),
    image,
    ImageLayout::Optimal,
    &[BufferImageCopy {
        buffer_offset: 0,
        buffer_row_length: 0,
        buffer_image_height: 0,
        image_subresource: default(),
        image_offset: Offset3d { x: 0, y: 0, z: 0 },
        image_extent: Extent3d {
            width,
            height,
            depth: 1,
        },
    }],
);

The request_transient_buffer_with_data function returns a handle bound to the lifetime of the frame parameter which prevents the common error of persisting references to frame allocated data after the frame has been submitted. At the beginning of a frame the linear allocators are reset, and the underlying buffers are recycled.

For this scheme to be production-ready it would also be important that the system track the amount of memory used each frame, and release excess memory that is unused over a longer period of time to the general allocator. As it is currently implemented, any buffers allocated by the transient memory pools will remain attached to those pools until shutdown.

Zeroed Memory

When memory is provided from the kernel to a desktop application, it’s well-defined that the contents of that memory are zeroed. While the mechanics differ between operating systems, this is safe for an application to rely on, and is important for security as un-cleared memory from other processes could contain secrets. With video memory allocations it’s… less straightforward.

On Windows, fresh video memory from the OS should always be zeroed. DX12 specifies that newly allocated video memory is always zeroed, and then provides an opt-out via D3D12_HEAP_FLAG_CREATE_NOT_ZEROED, where drivers may recycle memory within a single process without clearing it. Practically speaking, this means that Vulkan drivers on Windows also default to zeroing video memory before handing it off to an application.

On Linux the situation is the opposite. Not only do drivers avoid clearing memory within a process, but until recently amdgpu² did not even clear video memory from other processes. This means it’s vitally important that you manually clear video memory after receiving it, where that would be important to your application’s semantics. It’s a common enough source of problems that mesa has a frequently applied driconf quirk which forces the driver to zero allocated video memory.

To bring order to the chaos, VK_EXT_zero_initialize_device_memory is a new extension which introduces a flag, VK_MEMORY_ALLOCATE_ZERO_INITIALIZE_BIT_EXT, enabling applications to request the driver perform zero initialization on a per-allocation basis. Though note the default is still backwards compared to DX12 and Windows Vulkan.

This means that you have to throw a lock around all device memory allocations.↩
amdgpu is the kernel side vulkan driver for AMD GPUs on Linux.↩

Hello, World!

2025-06-02T00:00:00Z