DEV Community: LNATION

Introducing Object::Proto — A Prototype Object System for Perl

LNATION — Fri, 03 Apr 2026 11:54:34 +0000

Perl's object system is famously flexible. bless a reference, add some accessors, and you're in business. Over the years, modules like Moose, Moo, and Mouse have built increasingly sophisticated layers on top of that foundation — giving us type constraints, roles, lazy attributes, and declarative syntax.

But they all share the same bedrock: a blessed hash reference.

Object::Proto takes a less used approach. It stores objects as blessed arrays, maps property names to slot indices at compile time, and compiles accessors down to custom ops — the same mechanism Perl uses internally for built-in operations. The result is an object system that is type-safe, feature-rich, and significantly faster than the previously mentioned alternatives.

The Basics

use Object::Proto;

object 'Animal',
    'name:Str:required',
    'sound:Str:default(silence)',
    'age:Int';

my $cat = new Animal name => 'Whiskers', age => 3;
print $cat->name;      # Whiskers
print $cat->sound;     # silence
$cat->age(4);          # setter

The object keyword defines a class at compile time. Property specifications use a colon-separated format: name:Type:modifier. No hash lookups at runtime — $cat->name compiles to a direct array slot access.

Both positional and named constructors are supported:

my $cat = new Animal 'Whiskers', 'meow', 3;     # positional (fastest)
my $cat = new Animal name => 'Whiskers', age => 3; # named pairs

What You Get

Built-in Types (Zero Overhead)

Any  Defined  Str  Int  Num  Bool  ArrayRef  HashRef  CodeRef  Object

These are checked inline at the C level — no function call, no callback. You can also register custom types in Perl or in XS.

Slot Modifiers

object 'Person',
    'name:Str:required',
    'email:Str:required:readonly',
    'age:Int:default(0)',
    'nickname:Str:clearer:predicate',
    'settings:HashRef:lazy:builder(_build_settings)',
    'parent:Object:weak',
    'internal_id:Int:arg(_id)',       # constructor uses _id, accessor uses internal_id
    'score:Num:trigger(on_score_change)',
    'rank:Str:reader(get_rank):writer(set_rank)';

Everything you'd expect from a modern object system: required, readonly, default, lazy, builder, clearer, predicate, reader, writer, trigger, weak references, and arg (init_arg) — all compiled to C/XS.

Inheritance

object 'Animal', 'name:Str:required', 'sound:Str';

object 'Dog',
    extends => 'Animal',
    'breed:Str';

my $dog = new Dog name => 'Rex', sound => 'Woof', breed => 'Lab';
print $dog->isa('Animal');  # 1

Multiple inheritance and multi-level chains work as youl would expect:

object 'Triathlete',
    extends => ['Swimmer', 'Runner'],
    'event:Str';

Important note: because Object::Proto objects are arrays and Moo/Moose/Mouse objects are hashes, you cannot inherit from Moo, Moose, or Mouse classes (or vice versa). The internal representations are fundamentally incompatible. If you need to interoperate, use composition (roles or delegation via slots) rather than inheritance.

Roles

Roles work the way you'd expect — define a bundle of slots and method requirements, then compose them into any class. A role can carry its own attributes and demand that consuming classes implement specific methods:

use Object::Proto;

role('Printable', 'format:Str:default(text)');
requires('Printable', 'to_string');

object 'Document',
    'title:Str:required',
    'body:Str';

with('Document', 'Printable');

package Document;
sub to_string { $_[0]->title . ': ' . $_[0]->body }

The format slot from Printable is merged into Document at define time. If Document didn't provide a to_string method, the with call would croak. You can check role consumption at runtime with Object::Proto::does($obj, 'Printable').

Method Modifiers

You can wrap existing methods without subclassing. before runs code ahead of the original, after runs code after it, and around gives you full control — you receive the original method as $orig and decide whether (and how) to call it:

before 'bark' => sub {
    my ($self) = @_;
    warn "About to bark...";
};

after 'bark' => sub {
    my ($self) = @_;
    warn "Done barking.";
};

around 'bark' => sub {
    my ($orig, $self, @args) = @_;
    return uc $self->$orig(@args);
};

Multiple modifiers can be stacked on the same method. They're stored as linked lists in C, so the dispatch overhead is minimal.

Prototype Chains

This is where Object::Proto gets its name. Like JavaScript's prototype model, any object can delegate to another object. When you access a property that is undef in the current object, the lookup walks up the prototype chain until it finds a defined value:

my $defaults = new Animal name => 'Default', sound => 'silence';
my $cat = new Animal name => 'Whiskers';
$cat->set_prototype($defaults);

print $cat->sound;  # 'silence' — resolved from prototype

$cat has no sound of its own, so the accessor walks up to $defaults and returns 'silence'. Setting $cat->sound('meow') writes to $cat directly — prototypes are never mutated by child writes. You can inspect the full chain with Object::Proto::prototype_chain($obj) and measure its depth with Object::Proto::prototype_depth($obj).

Mutability Controls

Objects can be locked (preventing structural changes) or frozen (permanent deep immutability). A frozen object's setters will croak on any attempt to modify — useful for configuration objects, default prototypes, or any value you want to guarantee stays constant:

$obj->lock;       # prevent structural changes
$obj->unlock;
$obj->freeze;     # permanent immutability — setters will croak
$obj->is_frozen;  # true

Locking is reversible; freezing is not. The frozen check is implemented as a single bitflag test in C — it adds no measurable overhead to the normal (unfrozen) code path.

Cloning & Introspection

Object::Proto provides a full introspection API. You can clone objects (the clone is always fresh, unfrozen and unlocked, even if the original wasn't), list properties, inspect slot metadata, and walk the inheritance tree:

my $clone = Object::Proto::clone($obj);     # shallow copy, unfrozen
my @props = Object::Proto::properties('Dog');
my $info  = Object::Proto::slot_info('Dog', 'name');
my @chain = Object::Proto::ancestors('Dog');

slot_info returns a hashref with everything about a slot: its type, whether it's required, readonly, lazy, has a default, trigger, builder, and so on. Useful for building serializers, form generators, or debugging tools.

Singletons

Need a class that only ever has one instance? Mark it as a singleton and use ->instance() instead of new. The first call constructs the object; every subsequent call returns the same one:

object 'Config', 'db_host:Str', 'db_port:Int';
Object::Proto::singleton('Config');

my $c = Config->instance(db_host => 'localhost', db_port => 5432);
# Config->instance returns the same object every time after first call

This is handled at the C level — no Perl-side state variable or CHECK block trickery.

Function-Style Accessors

For the absolute fastest access, Object::Proto offers function-style accessors that bypass method dispatch entirely. These are compiled to custom ops at compile time — a direct array slot read/write with no entersub, no method resolution, no hash lookup:

use Object::Proto;

object 'Point', 'x:Num', 'y:Num';
Object::Proto::import_accessors('Point');

my $p = new Point 1.0, 2.0;
print x($p);         # 1.0 — custom op, not a method call
y($p, 3.0);          # set y to 3.0

Performance

Here are benchmarks from a mixed new + set + get workload:

                       Rate    Pure Hash  Pure Array    XS OO   Typed  Raw Hash Ref  XS func  Raw Hash
Pure Hash         1824921/s           --       -14%     -48%     -64%       -66%       -66%     -70%
Pure Array        2124357/s          16%         --     -40%     -58%       -60%       -61%     -65%
Object::Proto OO  3541833/s          94%        67%       --     -31%       -34%       -35%     -41%
Object::Proto T   5114883/s         180%       141%      44%       --        -4%        -6%     -15%
Raw Hash Ref      5331773/s         192%       151%      51%       4%         --        -2%     -12%
Object::Proto fn  5427162/s         197%       156%      53%       6%        2%          --     -10%
Raw Hash          6024884/s         230%       184%      70%      18%       13%        11%       --

The function-style path (XS func) runs slightly faster than raw hash reference access — while giving you a real object with type constraints, constructors, and a class hierarchy. The method-style path (XS OO) is nearly 2x faster than a pure-Perl hash-based object.

For hot set + get loops on pre-constructed objects, the XS function path has been measured at over 32 million operations per second — faster than a hash $hash{key} access.

Extending the Type System from XS

If you write XS modules, you can register types with C-level check functions that run at near-zero cost (~5 CPU cycles vs ~100 for Perl callbacks):

/* In your BOOT section */
#include "object_types.h"

static bool check_positive_int(pTHX_ SV *val) {
    return SvIOK(val) && SvIV(val) > 0;
}

BOOT:
    object_register_type_xs(aTHX_ "PositiveInt", check_positive_int, NULL);

use MyTypes;  # registers in BOOT
use Object::Proto;

object 'Counter', 'value:PositiveInt:required';

For Moo/Moose Users: Object::Proto::Sugar

If you prefer declarative Moo-style syntax, Object::Proto::Sugar wraps the XS layer with familiar keywords. Everything compiles down to the same custom ops underneath:

package Animal;
use Object::Proto::Sugar;

has name  => ( is => 'rw', isa => Str, required => 1 );
has sound => ( is => 'rw', isa => Str, default  => 'silence' );
has age   => ( is => 'rw', isa => Int );

sub speak { $_[0]->sound }

package Dog;
use Object::Proto::Sugar;

extends 'Animal';

has breed => ( is => 'rw', isa => Str );

package main;

my $dog = new Dog name => 'Rex', sound => 'Woof', breed => 'Lab';
print $dog->speak;         # Woof
print $dog->isa('Animal'); # 1

Every feature from the core module is available through the Sugar interface: lazy, builder, coerce, trigger, predicate, clearer, reader, writer, weak_ref, init_arg, roles (use Object::Proto::Sugar -role / with / requires), method modifiers (before, after, around), and function-style accessors via accessor => 1. The Sugar layer runs at compile time via BEGIN::Lift and then Devel::Hook via BIGIN and UNITCHECK hooks — by the time your first line of runtime code executes, everything has been compiled down to the same custom ops as the raw object keyword.

Sugar with Function-Style Accessors

Add accessor => 1 to a has declaration to get a function style accessor alongside the method style one. Then call import_accessors in your package so the functions are visible when your calling code compiles.

package Point;
use Object::Proto::Sugar;

has x => ( is => 'rw', isa => Num, accessor => 1 );
has y => ( is => 'rw', isa => Num, accessor => 1 );

package main;

Point->import_accessors;     # install before compilation

my $p = new Point x => 1.0, y => 2.0;
print x($p);       # 1.0 — compiled to custom op
y($p, 3.0);        # direct array write

Sugar Benchmarks vs Moo and Mouse

                       Rate       Moo     Mouse   Sugar   Sugar (fn)
Moo               1264320/s        --       -2%    -55%       -60%
Mouse             1290237/s        2%        --    -54%       -59%
Sugar (method)    2784378/s      120%      116%      --       -12%
Sugar (func)      3174093/s      151%      146%     14%         --

Sugar method-style is 2.2x Moo. Sugar function-style is 2.5x Moo.

A Note on Compatibility

Once again a reminder: because Object::Proto objects are arrays and Moo/Moose/Mouse objects are hashes, you cannot inherit across the boundary. extends 'My::Moo::Class' will not work. Use role or delegation to bridge the two worlds if needed. Within its own ecosystem — Object::Proto classes inheriting from other Object::Proto classes — everything works seamlessly, including multiple inheritance.

Object::Proto is available on CPAN and licensed under the Artistic License 2.0.

cpanm Object::Proto
cpanm Object::Proto::Sugar   # optional, for Moo-like syntax

MetaCPAN

Loo: Yet Another Way To Introspect Data

LNATION — Wed, 01 Apr 2026 07:48:49 +0000

A Side note: I'm currently on look out for a new contract or permanent opportunity. If you know of any relevant openings, I'd appreciate hearing from you. I am a proficient front-end developer also - email@lnation.org

If you've spent any time debugging Perl, you've used Data::Dumper. It's one of those modules that ships with every Perl installation, gets loaded into every debugging session, and does its job without complaint. But it also hasn't changed much in a long time. The output is monochrome, the internals are pure Perl, and code references remain opaque sub { "DUMMY" } blobs unless you enable Deparse and even then you do not get the response one would expect.

Loo is a new take on the same problem: dump Perl data structures to readable output, but do it in C, with colour, and with a built-in code deparser that walks the op tree directly.

Why Another Dumper?

Three reasons drove the creation of Loo:

Speed. Loo is implemented entirely in XS. The dump logic, string escaping, colour code generation, and op tree walking all happen in C. For large or deeply nested structures, this matters.

Colour out of the box. When your terminal supports it, Loo's output is coloured by default. Strings, numbers, hash keys, braces, blessed class names, regex patterns, and code all get distinct colours that can be customised. There's no separate module to install, no formatter to configure. It auto-detects terminal capability, respects $ENV{NO_COLOR}, and falls back to plain text when appropriate.

Code deparsing without B::Deparse. When you pass a code reference to Loo with deparsing enabled, it walks Perl's internal op tree in C and reconstructs the source. This is not a wrapper around B::Deparse — it's a standalone implementation that lives in the same XS compilation unit as the introspecter itself.

Getting Started

Loo provides a functional interface that mirrors Data::Dumper closely enough that switching is straightforward:

use Loo qw(Dump cDump ncDump dDump);

# Colour auto-detected based on terminal
print Dump({ name => 'Perl', version => 5.40 });

# Force colour on (useful when piping to a pager that supports ANSI)
print cDump([1, 2, 3]);

# Force colour off (useful for logging or file output)
print ncDump(\%ENV);

# Dump with code deparsing enabled
print dDump(sub { my ($x) = @_; return $x * 2 });

The OO interface supports method chaining and gives you access to the full set of configuration options:

my $loo = Loo->new([{ key => 'value' }], ['data']);
$loo->Indent(1)->Sortkeys(1)->Theme('monokai');
print $loo->Dump;

Data::Dumper Compatibility

Loo implements the same accessor interface as Data::Dumper: Indent, Terse, Varname, Useqq, Quotekeys, Sortkeys, Maxdepth, Maxrecurse, Purity, Deepcopy, Pair, Freezer, Toaster, Bless, Deparse, Trailingcomma, Sparseseen, and Pad. If you have existing code that configures a Data::Dumper object, the same method calls work on a Loo object and is faster.

Beyond that, Loo adds a few options that Data::Dumper doesn't have:

Indentwidth($n) — control the number of characters per indent level (default 2)
Usetabs($bool) — indent with tabs instead of spaces

Colour Customisation

Loo ships with four built-in themes: default, light (optimised for light terminal backgrounds), monokai, and none.

For fine-grained control, the Colour method accepts a hash specifying foreground and background colours for 17 distinct syntax elements:

$loo->Colour({
    string_fg  => 'green',
    key_fg     => 'magenta',
    number_fg  => 'cyan',
    brace_fg   => 'bright_black',
    undef_fg   => 'red',
});

The colorable elements cover every visual component of the output: string, number, key, brace, bracket, paren, arrow, comma, undef, blessed, regex, code, variable, quote, keyword, operator, and comment.

Colour codes are pre-computed once at configuration time, so there's no per-character overhead during the dump.

The Deparser

The most unusual feature of Loo is its built-in code deparser. When you enable deparsing, Loo walks the Perl op tree directly in C — the same internal structure that the Perl interpreter executes — and reconstructs Perl source code from it.

my $loo = Loo->new([\&Some::function]);
$loo->Deparse(1);
print $loo->Dump;

This means code references in your data structures are no longer black boxes. You see the actual code that will be run from the code. NOTE: It may not be identical to the code written as some postfix operations are lost as I am deparsing the compiled op tree itself.

Getting this to work across Perl versions was one of the harder parts of the project. The op tree structure has changed across Perl releases — OP_PADSV_STORE appeared in 5.38, OP_EMPTYAVHV landed in 5.36 as an enum rather than a #define, and PADNAME typedefs shifted between 5.20 and 5.22. Loo handles all of this with version-conditional compilation, supporting Perl 5.10 through to the latest releases.

Reusable C Headers

Loo's XS code is organised into modular C headers:

loo.h — core definitions, themes, colour element names
loo_colour.h — ANSI colour code generation
loo_escape.h — string escaping
loo_dump.h — recursive data structure dumping
loo_deparse.h — op tree walking and code reconstruction

These headers are installed alongside the Perl module, and Loo->include_dir returns their path. This means other XS modules can reuse Loo's colour or escaping logic without duplicating the C code.

Auto-Detection Done Right

Loo follows the no-color.org convention and layers several checks to decide whether to emit ANSI codes:

If $Loo::USE_COLOUR is set, that takes precedence
If $ENV{NO_COLOR} is set, colour is disabled
If $ENV{TERM} is "dumb", colour is disabled
If STDOUT is not a terminal, colour is disabled
Otherwise, colour is enabled

This means Dump() does the right thing whether you're debugging interactively, piping to a file, or running in CI. And cDump() / ncDump() are there when you need to override.

Installation

Loo is available on CPAN:

cpanm Loo

It requires Perl 5.008003 or later and a C compiler (which you already have if you've ever installed an XS module).

Closing Thoughts

Data::Dumper is a workhorse that has served the Perl community well for decades. Loo isn't trying to replace it everywhere — but if you spend a lot of time reading dump output, colour and deparsing make a real difference. And if you're dumping large structures in production logging or tooling, the XS implementation gives you that output faster.

Give it a look. Your eyes may thank you.

Learning XS - Sharing Reusable C Headers Between Perl XS Distributions

LNATION — Sun, 29 Mar 2026 12:00:05 +0000

Introduction

Since I last wrote a XS tutorial my knowledge within C has increased this has come from improvements in LLM software that has assisted in improving my knowledge where previously I would be stuck. This knowledge and software has since enabled me to craft more elegant and efficient XS implementations.

Today I will share with you my technique for writing reusable C/XS code.

One of the most powerful patterns in XS development is writing your core logic in pure C header files. This gives you:

Zero-cost reuse - no runtime linking, no shared libraries, just a #include line.
No Perl dependency in the C layer - your headers work in any C project
Compile-time inlining - the compiler sees everything, optimises aggressively
Simple distribution - headers are installed alongside the Perl module via PM

This tutorial walks through the complete pattern step by step, using a minimal working example you can build and run yourself.

The Example

We will create two distributions:

Abacus - a provider distribution that ships a reusable pure-C abacus_math.h header containing simple arithmetic functions
Tally - a consumer distribution that #includes the Abacus header to build its own XS module, without duplicating any C code

As always lets start by creating the distributions that we will need for this tutorial. Open your terminal and run module-starter. If you are using a modern version of Module::Starter then the command has changed slightly since my last posts.

  module-starter --module=Abacus --author="LNATION <email@lnation.org>"
  module-starter --module=Tally --author="LNATION <email@lnation.org>"

Part 1: The Provider Distribution (Abacus)

Write the pure-C header

This is the reusable part. It has zero Perl dependencies - just standard C.

Now enter the Abacus and create the include directory:

  cd Abucus
  mkdir include

Then create a new file abacus_math.h:

  touch abacus_math.h
  vim abacus_math.h

Paste the following code into the file:

#ifndef ABACUS_MATH_H
#define ABACUS_MATH_H

/*
 * abacus_math.h - Pure C arithmetic library (no Perl dependencies)
 *
 * This header is the reusable entry point for any C or XS project
 * that needs basic arithmetic operations. It has ZERO Perl/XS
 * dependencies.
 *
 * Usage from another XS module:
 *
 *     #include "abacus_math.h"
 *
 * Build: add -I/path/to/Abacus/include to your compiler flags.
 */

#include <stdint.h>

/* ── Error handling hook ─────────────────────────────────────────
 *
 * Consumers can #define ABACUS_FATAL(msg) before including this
 * header to route errors through their own mechanism.
 *
 * In an XS module you would typically do:
 *
 *     #define ABACUS_FATAL(msg) croak("%s", (msg))
 *     #include "abacus_math.h"
 *
 * In plain C the default behaviour is fprintf + abort.
 */
#ifndef ABACUS_FATAL
#  include <stdio.h>
#  include <stdlib.h>
#  define ABACUS_FATAL(msg) do { \
       fprintf(stderr, "abacus fatal: %s\n", (msg)); \
       abort(); \
   } while (0)
#endif

/* ── Arithmetic operations ───────────────────────────────────── */

static inline int32_t
abacus_add(int32_t a, int32_t b) {
    return a + b;
}

static inline int32_t
abacus_subtract(int32_t a, int32_t b) {
    return a - b;
}

static inline int32_t
abacus_multiply(int32_t a, int32_t b) {
    return a * b;
}

static inline int32_t
abacus_divide(int32_t a, int32_t b) {
    if (b == 0) {
        ABACUS_FATAL("division by zero");
    }
    return a / b;
}

static inline int32_t
abacus_factorial(int32_t n) {
    int32_t result = 1;
    int32_t i;
    if (n < 0) {
        ABACUS_FATAL("factorial of negative number");
    }
    for (i = 2; i <= n; i++) {
        result *= i;
    }
    return result;
}

#endif /* ABACUS_MATH_H */

The code above demonstrates three critical design patterns for reusable C headers:

static inline functions eliminate linker complications by giving each translation unit its own copy of the function. The compiler can then inline these small arithmetic operations directly into the call site, producing zero-overhead abstractions. This is key to the "zero-cost reuse" principle—there is no shared library dependency, no function call overhead, just pure generated code.

The ABACUS_FATAL macro hook provides a customization point for error handling. By default, it calls fprintf() and abort() in standalone C programs; but consumers can #define ABACUS_FATAL(msg) croak("%s", (msg)) before including the header to integrate seamlessly with Perl's exception system. This single mechanism allows the same C header to work across Perl XS, plain C, and other environments without code duplication.

The use of only stdint.h integers and no Perl types ensures the header remains truly portable. There are no SV* pointers, no pTHX context variables, no XSUB.h includes—just standard C99 types. This purity is what allows the header to be #included into any C or XS project without creating hidden Perl dependencies at the C layer.

Write the Perl-facing XS header

Next we will add another header which will hold the Perl/XS specific logic. Inside the include directory create a new file called abacus.h. The rational behind this thin wrapper is to pull in Perl's headers and sets up the ABACUS_FATAL macro to use croak(). To reiterate only a XS distribution should include this header, whereas abacus_math.h is generic and could be used by other languages which bind C.

    touch abacus.h
    vim abacus.h

Paste the following code into the file

#ifndef ABACUS_H
#define ABACUS_H

/*
 * abacus.h - Perl XS wrapper header for the Abacus library
 *
 * This header sets up Perl-specific error handling and includes
 * the pure C core library.
 *
 * For reuse from OTHER XS modules without Perl overhead, include
 * abacus_math.h directly instead (see that header for usage).
 */

#define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#include "ppport.h"

/* Route fatal errors through Perl's core croak() */
#define ABACUS_FATAL(msg) croak("%s", (msg))

/* Pull in the pure-C library */
#include "abacus_math.h"

#endif /* ABACUS_H */

Now any .xs file can #include "abacus.h" and get the full Perl/XS environment plus all the pure-C functions, with errors properly integrated.

Write the XS file

Next we will create the XS file, return to the root directory and then enter the lib directoy where you should see the Abacus.pm file already. Create a new XS file called Abacus.xs. This will be the glue that exposes the C functions to Perl.

  cd ../lib
  touch Abacus.xs
  vim Abacus.xs

#include "abacus.h"

MODULE = Abacus  PACKAGE = Abacus

PROTOTYPES: DISABLE

int
add(a, b)
    int a
    int b
  CODE:
    RETVAL = abacus_add(a, b);
  OUTPUT:
    RETVAL

int
subtract(a, b)
    int a
    int b
  CODE:
    RETVAL = abacus_subtract(a, b);
  OUTPUT:
    RETVAL

int
multiply(a, b)
    int a
    int b
  CODE:
    RETVAL = abacus_multiply(a, b);
  OUTPUT:
    RETVAL

int
divide(a, b)
    int a
    int b
  CODE:
    RETVAL = abacus_divide(a, b);
  OUTPUT:
    RETVAL

int
factorial(n)
    int n
  CODE:
    RETVAL = abacus_factorial(n);
  OUTPUT:
    RETVAL

As you can see we include abacus.h which pulls in all the C that we need to create our XS module. We then define add, subtract, multiply, divide and factorial as XSUBs. As you should know by now XSUBs can be called directly from your perl code.

Write the Perl module with `include_dir()`

Next open the pm file and update to add an exporter for the XSUBS we have just created.

package Abacus;

use 5.008003;
use strict;
use warnings;

our $VERSION = '0.01';

use Exporter 'import';
our @EXPORT_OK = qw(add subtract multiply divide factorial);

require XSLoader;
XSLoader::load('Abacus', $VERSION);

Now the critical piece that makes header sharing work. A include_dir() method which returns the path to the installed headers so that consumer distributions can find them at build time.

sub include_dir {
    my $dir = $INC{'Abacus.pm'};
    $dir =~ s{Abacus\.pm$}{Abacus/include};
    return $dir;
}

1;

How include_dir() works:

When Perl loads Abacus.pm, it records the full path in %INC (e.g. /usr/lib/perl5/site_perl/Abacus.pm)
include_dir() replaces Abacus.pm with Abacus/include
That directory exists because Makefile.PL installs the headers there (see next step)

Write the Makefile.PL that installs headers

The PM hash is what makes headers available to other distributions after install. It maps source files to their installation destinations.

Abacus/Makefile.PL

use 5.008003;
use strict;
use warnings;
use ExtUtils::MakeMaker;

WriteMakefile(
    NAME             => 'Abacus',
    AUTHOR           => 'Your Name <you@example.com>',
    VERSION_FROM     => 'lib/Abacus.pm',
    ABSTRACT_FROM    => 'lib/Abacus.pm',
    LICENSE          => 'artistic_2',
    MIN_PERL_VERSION => '5.008003',
    CONFIGURE_REQUIRES => {
        'ExtUtils::MakeMaker' => '0',
    },
    TEST_REQUIRES => {
        'Test::More' => '0',
    },
    PREREQ_PM => {},
    XSMULTI => 1,
    # XS configuration
    INC    => '-I. -Iinclude',
    OBJECT => '$(O_FILES)',

    # *** THIS IS THE KEY PART ***
    # Install headers alongside the module so dependent
    # distributions can find them via Abacus->include_dir()
    PM => {
        'lib/Abacus.pm'           => '$(INST_LIB)/Abacus.pm',
        'include/abacus.h'        => '$(INST_LIB)/Abacus/include/abacus.h',
        'include/abacus_math.h'   => '$(INST_LIB)/Abacus/include/abacus_math.h',
    },

    dist  => { COMPRESS => 'gzip -9f', SUFFIX => 'gz' },
    clean => { FILES => 'Abacus-*' },
);

The PM hash does two things:

Installs Abacus.pm as normal
Copies the header files into Abacus/include/ alongside the module

After make install, the filesystem looks like:

site_perl/
  Abacus.pm
  Abacus/
    include/
      abacus.h
      abacus_math.h

Write a test

Abacus/t/01-basic.t

use strict;
use warnings;
use Test::More;
use Abacus qw(add subtract multiply divide factorial);

is(add(2, 3),       5,   'add');
is(subtract(10, 4), 6,   'subtract');
is(multiply(3, 7),  21,  'multiply');
is(divide(20, 4),   5,   'divide');
is(factorial(5),     120, 'factorial');

eval { divide(1, 0) };
like($@, qr/division by zero/, 'divide by zero croaks');

eval { factorial(-1) };
like($@, qr/negative/, 'negative factorial croaks');

done_testing;

Build and install Abacus

cd Abacus
perl Makefile.PL
make
make test
make install          # installs headers into site_perl

Part 2: The Consumer Distribution (Tally)

Tally is a separate distribution that reuses Abacus's C arithmetic without duplicating any code. It adds its own "running total" functionality on top.

Write the Makefile.PL that finds Abacus headers

This is where the consumer locates the provider's headers. The two-step resolution strategy supports both installed (CPAN) and development (sibling
directory) scenarios.

Tally/Makefile.PL

use 5.008003;
use strict;
use warnings;
use ExtUtils::MakeMaker;

# Resolve Abacus include directory:
#   1. Try installed Abacus module (CPAN / system)
#   2. Fall back to sibling directory (development)
my $abacus_inc;
eval {
    no warnings 'redefine';
    local *XSLoader::load = sub {};  # skip XS bootstrap
    require Abacus;
    my $dir = Abacus->include_dir();
    $abacus_inc = $dir if $dir && -d $dir;
};
if (!$abacus_inc && -d '../Abacus/include') {
    $abacus_inc = '../Abacus/include';
}
die "Cannot find Abacus include directory.\n"
  . "Install Abacus or place it as a sibling directory.\n"
    unless $abacus_inc;

WriteMakefile(
    NAME             => 'Tally',
    AUTHOR           => 'Your Name <you@example.com>',
    VERSION_FROM     => 'lib/Tally.pm',
    ABSTRACT_FROM    => 'lib/Tally.pm',
    LICENSE          => 'artistic_2',
    MIN_PERL_VERSION => '5.008003',
    CONFIGURE_REQUIRES => {
        'ExtUtils::MakeMaker' => '0',
        'Abacus'              => '0.01',
    },
    TEST_REQUIRES => {
        'Test::More' => '0',
    },
    PREREQ_PM => {
        'Abacus' => '0.01',
    },

    # Point the compiler at Abacus's installed headers
    INC    => "-I$abacus_inc",
    OBJECT => '$(O_FILES)',

    dist  => { COMPRESS => 'gzip -9f', SUFFIX => 'gz' },
    clean => { FILES => 'Tally-*' },
);

Let's walk through the header resolution:

Try the installed path first - require Abacus loads the module, then Abacus->include_dir() returns the path where the headers were installed. We stub out XSLoader::load because we only need the pure-Perl include_dir() method, not the XS functions.
Fall back to sibling directory - during development, Abacus and Tally often live side by side. ../Abacus/include handles this case.
Die with a clear message if neither path works.

The resolved path is passed to INC, which adds it to the C compiler's include search path (-I/path/to/Abacus/include).

Abacus is listed in both CONFIGURE_REQUIRES and PREREQ_PM:

CONFIGURE_REQUIRES ensures Abacus is installed before Makefile.PL runs (needed because we require Abacus at configure time)
PREREQ_PM ensures it is available at runtime too

Write the XS file

This is where the reuse happens. Tally includes abacus_math.h directly -
no Perl coupling, just pure C function calls.

Tally/Tally.xs

#define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"

/* Hook Abacus errors into Perl's croak() */
#define ABACUS_FATAL(msg) croak("%s", (msg))

/* Include the pure-C header from Abacus - no Perl deps in the header */
#include "abacus_math.h"

/* ── Tally's own C logic, built on top of Abacus ─────────────── */

typedef struct {
    int32_t total;
} tally_state_t;

static inline void
tally_init(tally_state_t *state) {
    state->total = 0;
}

static inline int32_t
tally_add(tally_state_t *state, int32_t value) {
    state->total = abacus_add(state->total, value);
    return state->total;
}

static inline int32_t
tally_subtract(tally_state_t *state, int32_t value) {
    state->total = abacus_subtract(state->total, value);
    return state->total;
}

static inline int32_t
tally_multiply_total(tally_state_t *state, int32_t value) {
    state->total = abacus_multiply(state->total, value);
    return state->total;
}

static inline int32_t
tally_get(tally_state_t *state) {
    return state->total;
}

static inline void
tally_reset(tally_state_t *state) {
    state->total = 0;
}

/* ── XS bindings ─────────────────────────────────────────────── */

MODULE = Tally  PACKAGE = Tally

PROTOTYPES: DISABLE

SV *
new(class)
    const char *class
  CODE:
    tally_state_t *state;
    Newxz(state, 1, tally_state_t);
    tally_init(state);
    RETVAL = newSV(0);
    sv_setref_pv(RETVAL, class, (void *)state);
  OUTPUT:
    RETVAL

int
add(self, value)
    SV *self
    int value
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    RETVAL = tally_add(state, value);
  OUTPUT:
    RETVAL

int
subtract(self, value)
    SV *self
    int value
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    RETVAL = tally_subtract(state, value);
  OUTPUT:
    RETVAL

int
multiply_total(self, value)
    SV *self
    int value
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    RETVAL = tally_multiply_total(state, value);
  OUTPUT:
    RETVAL

int
total(self)
    SV *self
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    RETVAL = tally_get(state);
  OUTPUT:
    RETVAL

void
reset(self)
    SV *self
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    tally_reset(state);

void
DESTROY(self)
    SV *self
  CODE:
    tally_state_t *state = INT2PTR(tally_state_t *, SvIV(SvRV(self)));
    Safefree(state);

Notice that Tally includes abacus_math.h (the pure C header), not abacus.h (the Perl-facing wrapper). This is intentional - Tally has its own Perl/XS setup and only needs the C functions.

Write the Perl module

Tally/lib/Tally.pm

package Tally;

use 5.008003;
use strict;
use warnings;

our $VERSION = '0.01';

require XSLoader;
XSLoader::load('Tally', $VERSION);

1;

__END__

=head1 NAME

Tally - Running total calculator using Abacus C headers

=head1 SYNOPSIS

    use Tally;

    my $t = Tally->new;
    $t->add(10);        # total is now 10
    $t->add(5);         # total is now 15
    $t->subtract(3);    # total is now 12
    $t->multiply_total(2);  # total is now 24
    say $t->total;      # 24
    $t->reset;          # back to 0

=cut

Write a test

Tally/t/01-basic.t

use strict;
use warnings;
use Test::More;

use_ok('Tally');

my $t = Tally->new;
isa_ok($t, 'Tally');

is($t->total, 0, 'starts at zero');

is($t->add(10), 10, 'add 10');
is($t->add(5),  15, 'add 5');
is($t->subtract(3), 12, 'subtract 3');
is($t->multiply_total(2), 24, 'multiply by 2');
is($t->total, 24, 'total is 24');

$t->reset;
is($t->total, 0, 'reset to zero');

done_testing;

Build Tally (development mode)

cd Tally
perl Makefile.PL     # finds ../Abacus/include automatically
make
make test

I hope you found this tutorial useful! If you have questions about XS, C header reuse, or building modular Perl/C libraries, please leave a message.

Horus, Apophis, and Sekhmet: An C/XS Identifier Stack for Perl

LNATION — Sun, 29 Mar 2026 09:52:09 +0000

Three modules, one goal: fast, correct identifier generation in Perl with zero runtime dependencies. Horus generates UUIDs. Sekhmet generates ULIDs. Apophis uses deterministic UUIDs to build content-addressable storage. All three are implemented in C, exposed through XS, and designed to work together.

Horus: Every UUID Version, One Module

Horus implements all UUID versions defined in RFC 9562 -- v1 through v8, plus NIL and MAX. The entire engine is C, compiled once, called millions of times per second.

use Horus qw(:all);

my $random   = uuid_v4();                         # 122 random bits
my $sortable = uuid_v7();                         # timestamp + random, sortable
my $fixed    = uuid_v5(UUID_NS_DNS, "example.com"); # deterministic, always the same

Why multiple versions matter

Each version solves a different problem:

v4 is the workhorse. 122 bits of randomness, no coordination needed. Use it for session tokens, request IDs, anything where uniqueness is all you need.

v7 embeds a millisecond timestamp in the high bits, making UUIDs lexicographically sortable. Database indexes love this -- new rows append instead of scattering across B-tree pages. Horus guarantees monotonic ordering within the same millisecond.

my @ids = map { uuid_v7() } 1..3;
# 019d38f6-3e9a-765c-ae1c-1cfeb0c30000
# 019d38f6-3e9a-765c-ae1c-1cfeb0c40000
# 019d38f6-3e9a-765c-ae1c-1cfeb0c50000
# String sort == chronological sort

v5 is deterministic. Given the same namespace and name, it always produces the same UUID. This is the foundation Apophis builds on... the same content, the same identifier, every time.

my $a = uuid_v5(UUID_NS_DNS, "example.com");
my $b = uuid_v5(UUID_NS_DNS, "example.com");
# $a eq $b -- always

Ten output formats

Every generator accepts a format parameter. Convert between them freely:

my $id = uuid_v4();

uuid_convert($id, UUID_FMT_STR);      # 550e8400-e29b-41d4-a716-446655440000
uuid_convert($id, UUID_FMT_HEX);      # 550e8400e29b41d4a716446655440000
uuid_convert($id, UUID_FMT_BRACES);   # {550e8400-e29b-41d4-a716-446655440000}
uuid_convert($id, UUID_FMT_URN);      # urn:uuid:550e8400-e29b-41d4-a716-446655440000
uuid_convert($id, UUID_FMT_BASE64);   # VQ6EAOKbQdSnFkRmVUQAAA

Bulk generation

When you need thousands of IDs, crossing the Perl/C boundary once beats crossing it thousands of times:

my @ids = uuid_v4_bulk(10_000);  # single call, 10k UUIDs back

Utilities

uuid_validate($string);          # is this a valid UUID?
uuid_version($string);           # which version? (1-8)
uuid_time($v7_uuid);             # extract epoch seconds from v7/v6
uuid_cmp($a, $b);                # sort comparison (-1, 0, 1)

Sekhmet: ULIDs for When You Need Sortable and Compact

A ULID is 26 characters of Crockford base32 encoding: 10 characters of millisecond timestamp followed by 16 characters of randomness. They sort lexicographically by time, they are URL-safe, and they are shorter than UUIDs.

use Sekhmet qw(:all);

my $ulid = ulid();
# 06EKHXHYKAT25K0YQJHN6A6YJR

Monotonic mode

If you generate multiple ULIDs within the same millisecond, the random component increments to guarantee strict ordering:

my $a = ulid_monotonic();
my $b = ulid_monotonic();
my $c = ulid_monotonic();
# $a lt $b lt $c -- guaranteed, even within the same millisecond

Time extraction

The timestamp is baked into the ULID. Extract it without a database lookup:

my $ulid = ulid();
my $epoch = ulid_time($ulid);       # 1774777155.226
my $ms    = ulid_time_ms($ulid);    # 1774777155226

UUID interoperability

ULIDs and UUID v7 share the same structure -- 48-bit timestamp, random fill. Convert between them losslessly:

my $ulid = ulid();
my $uuid = ulid_to_uuid($ulid);    # standard UUID v7 string
# Useful when your API expects UUIDs but you generate ULIDs internally

When to use Sekhmet vs Horus

Use Sekhmet (ulid()) when you want compact, sortable, human friendly identifiers for log entries, event streams, anything displayed in a UI. Use Horus (uuid_v7()) when you need standard UUID format for compatibility with systems that expect 36-character hyphenated strings. Use Horus
(uuid_v4()) when you need pure randomness with no timestamp leakage.

Apophis: Content-Addressable Storage

Apophis answers the question: "Have I seen this content before?" It hashes content with UUID v5 to produce a deterministic identifier, then stores the content in a sharded directory tree. Same content always maps to the same path. Different content never collides.

use Apophis;

my $store = Apophis->new(
    namespace => 'my-app',
    store_dir => '/var/data/cas',
);

my $id = $store->store(\"Hello, world!");
# 3e856e0f-c7ac-569e-827b-40df723c326f

my $id2 = $store->store(\"Hello, world!");
# 3e856e0f-c7ac-569e-827b-40df723c326f  -- same content, same ID

How storage works

Content is stored in a two-level hex-sharded directory tree derived from the UUID. The first four hex characters become two directory levels:

/var/data/cas/
  3e/85/3e856e0f-c7ac-569e-827b-40df723c326f

This gives 65,536 possible directories -- enough to keep any single directory from growing too large, even with millions of files.

Writes are atomic: content goes to a temporary file first, then is renamed into place. A crash mid-write leaves no partial files.

Identification without storage

Sometimes you just want the identifier:

my $id = $store->identify(\"some content");     # UUID, no write
my $id = $store->identify_file("/path/to/big.iso");  # streams in 64KB chunks

File identification is streaming -- a 10GB file uses the same memory as a 10KB file.

Metadata

Attach arbitrary metadata as a sidecar:

my $id = $store->store(\"image data", meta => {
    mime_type     => 'image/png',
    original_name => 'photo.png',
    uploaded_by   => 'user-42',
});

my $meta = $store->meta($id);
# { mime_type => 'image/png', original_name => 'photo.png', ... }

Namespace isolation

The namespace parameter creates a separate UUID v5 namespace. The same content under different namespaces produces different identifiers:

my $a = Apophis->new(namespace => 'uploads');
my $b = Apophis->new(namespace => 'cache');

$a->identify(\"data") ne $b->identify(\"data");  # different IDs

This lets you run multiple independent stores without collision.

Verification

Content-addressable storage has a built-in integrity check: re-hash the content and compare to the filename.

if ($store->verify($id)) {
    # content matches its identifier -- no corruption
}

How They Fit Together

Horus (Foundation)
  |-- UUID v1-v8, NIL, MAX
  |-- C headers reused by downstream XS modules
  |
  |--- Apophis (Content-addressable storage)
  |      Uses UUID v5 for deterministic content identification
  |
  |--- Sekhmet (ULID generation)
         Uses Horus C primitives for Crockford base32, CSPRNG, timestamps

Horus is the foundation. Its C headers are standalone -- no Perl types, no interpreter context. Apophis and Sekhmet include them at compile time via Horus->include_dir().

A practical example using all three:

use Horus qw(:all);
use Apophis;
use Sekhmet qw(:all);

# Event tracking system
my $event_id  = ulid_monotonic();              # sortable event identifier
my $session   = uuid_v4();                     # random session token
my $store     = Apophis->new(namespace => 'events', store_dir => '/var/events');

# Store event payload, get content-addressable ID
my $payload = encode_json({ action => 'click', target => 'button-1' });
my $content_id = $store->store(\$payload, meta => {
    event_id   => $event_id,
    session_id => $session,
    timestamp  => ulid_time($event_id),
});

# Later: retrieve by content hash
my $data = $store->fetch($content_id);

# Or find when the event happened from the ULID
my $when = ulid_time($event_id);

Each module handles one concern well. Horus generates identifiers. Sekhmet adds time sortable compact identifiers. Apophis maps content to identifiers and manages storage. No module tries to do what another already does.

Performance

All three modules use custom ops on Perl 5.14+ to eliminate subroutine dispatch overhead. The hot paths are pure C with no Perl API calls.

Getting Started

cpanm Horus
cpanm Sekhmet
cpanm Apophis

All three are on CPAN under the
Artistic License 2.0.

Eshu: Indentation Fixer for Eight Languages, Written in C

LNATION — Sun, 29 Mar 2026 07:03:48 +0000

Most code formatters want to own your style. They have opinions about brace placement, line length, trailing commas, and a hundred other things you never asked for. Sometimes you just want the indentation fixed. Tabs consistent, nesting correct, content untouched.

That is was the goal for Eshu and exactly what it does. It reads source code line by line, tracks nesting depth through a state machine, rewrites the leading whitespace, and leaves everything else alone. The entire engine is written in C, exposed to Perl through XS, and ships with a CLI that can check, diff, or fix files in place. The distribution also ships with a vim plugin as that is my editor of choice.

Eight languages, one tool

C | Perl | XS | XML | HTML | CSS | JavaScript | POD

Each language gets its own scanner with its own state machine. They share a common architecture which track depth, emit indentation and advance but each state machine actually handles the constructs that make the specific language awkward to indent.

Perl has heredocs, quoted constructs (qw(), qq{}, s///), and embedded
POD. JavaScript has template literals with nested ${} interpolation. XS
files switch between C and Perl conventions at the MODULE = boundary. HTML
has void elements and verbatim zones inside <pre> and <script>. Each of these needs specific handling, and getting any of them wrong means corrupting content visually.

Why C?

Indentation fixing is embarrassingly linear. You read a line, update state, emit the line with new leading whitespace, repeat. There is no tree to build, no AST to walk, no multipass resolution. A single-pass scanner in C processes a large codebase in milliseconds.

The engine is implemented entirely in standalone C header files -- ten of them, roughly 3,600 lines total. They have no Perl dependencies. No SV*, no croak(), no interpreter context. Just stdlib.h, string.h, and ctype.h. This means they can be reused from any C program or language that can bind them, not just my Perl XS modules.

include/
  eshu.h              Core types, config, buffer, language enum
  eshu_c.h            C scanner
  eshu_pl.h           Perl scanner (heredoc, regex, qw, POD)
  eshu_xs.h           XS dual-mode scanner
  eshu_xml.h          XML/HTML scanner
  eshu_css.h          CSS scanner
  eshu_js.h           JavaScript scanner (template literals)
  eshu_pod.h          POD scanner
  eshu_file.h         File I/O, directory walking, binary detection
  eshu_diff.h         Unified diff generation

How the scanner works

Every language scanner follows the same pattern. For each line of input:

pre-adjust depth --> emit indent --> copy content --> post-adjust depth

A closing brace on a line means you dedent before emitting that line. An opening brace means you indent the next line. The scanner maintains a state enum to know whether it is inside a string, a comment, a heredoc, a regex, or regular code. State transitions happen character by character within the scan function; depth changes happen at line boundaries.

The Perl scanner, for example, tracks 14 distinct states: regular code, double-quoted strings, single-quoted strings, regex, heredoc (both standard and indented), qw, qq, q, POD, line comments, and block comments. It detects heredoc terminators, remembers whether the variant is indented (<<~EOF), buffers the body verbatim, and resumes normal scanning after the terminator.

The hard parts

Perl: Is `/` division or regex?

The classic Perl parsing problem. Eshu tracks whether the previous meaningful token was a value (a variable, a closing bracket, a number) or an operator. If it was a value, / is division. Otherwise, it opens a regex. This is the same heuristic that syntax highlighters use, and it covers real-world code well.

XS: Two languages in one file

An XS file is C code at the top and a Perl/C hybrid below MODULE =. Eshu detects the boundary and switches scanners. Below the boundary, it tracks XSUB blocks (each new function declaration resets depth), labels like CODE:, OUTPUT:, and INIT:, and special cases like BOOT: sections that use shallower indentation.

JavaScript: Template literals with nested interpolation

A backtick string in JavaScript can contain ${expr}, and that expression can contain braces, function calls, even another template literal. Eshu maintains a depth counter for interpolation braces so it knows when the } closes the interpolation versus when it closes a block inside the interpolation.

HTML: Script blocks need JavaScript rules

Content inside <script> tags is JavaScript, not HTML. Eshu collects the entire script block, passes it through the JavaScript scanner for reindentation, then splices it back at the correct HTML depth. The same applies to recognising void elements (<br>, <img>, etc.) that should not increase nesting depth.

The CLI

Eshu ships with a command-line tool that supports the three modes you actually need:

# Preview what would change
eshu --diff lib/

# Check in CI (exit 1 if anything needs fixing)
eshu --check lib/ t/

# Fix in place
eshu --fix lib/

By default, nothing is modified. You have to explicitly ask for --fix. Language is detected from file extensions, but can be overridden with --lang. You can filter files with --exclude and --include (regex patterns), choose tabs or spaces, set the indent width, and even restrict processing to a line range within a file.

Directory processing is recursive by default, skips binary files (detected by sampling the first 8KB for NUL bytes), respects a 1MB size limit, and follows file symlinks but not directory symlinks.

The Perl API

Everything the CLI does is available programmatically:

use Eshu;

# Fix a string
my $fixed = Eshu->indent_pl($source, spaces => 4);

# Auto-detect language and process
my $result = Eshu->indent_file('lib/App.pm',
    fix  => 1,
    diff => 1,
);
say $result->{diff} if $result->{status} eq 'changed';

# Process an entire directory
my $report = Eshu->indent_dir('lib/',
    fix       => 1,
    recursive => 1,
    exclude   => [qr/\.bak$/],
);
say "$report->{files_changed} files fixed";

Each language also has a direct method: indent_c, indent_xs, indent_xml, indent_html, indent_css, indent_js, indent_pod.

Idempotent by design

Running Eshu twice produces the same result as running it once. This is not just a goal, it is tested. The test suite includes real-world Perl example, verifies that processing them does not crash, and asserts that a second pass produces identical output.

This matters for CI integration. If eshu --check passes, you know that running eshu --fix would be a no-op. There is no oscillation, no cascading reformats, no "fix the fix" loops.

What it does not do

Eshu does not reformat code. It does not move braces, break long lines, sort imports, add or remove semicolons, or have opinions about blank lines. It touches leading whitespace and nothing else. Diffs are clean: every changed line shows only the whitespace prefix changing.

This is a deliberate constraint. A tool that only fixes indentation is a tool you can run on any codebase without fear. It will not start a style war. It will not produce a 10,000 line diff that buries your actual changes. It will make the nesting visible and get out of the way.

Vim integration

Eshu ships with a Vim plugin in the distribution. It pipes the current buffer through eshu and replaces the content in place, with automatic language detection and cursor position preservation.

Installation

The easiest way with Vim 8+ native packages:

mkdir -p ~/.vim/pack/eshu/start
ln -s /path/to/Eshu/vim ~/.vim/pack/eshu/start/eshu

For Neovim:

mkdir -p ~/.local/share/nvim/site/pack/eshu/start
ln -s /path/to/Eshu/vim ~/.local/share/nvim/site/pack/eshu/start/eshu

Or if you prefer vim-plug:

Plug '/path/to/Eshu/vim'

Or just source it directly in your .vimrc:

source /path/to/Eshu/vim/plugin/eshu.vim

Usage

Once loaded, you get two commands and a default keybinding:

Command	Mode	What it does
`:EshuFix`	Normal	Fix indentation for the entire file
`:EshuFixRange`	Visual	Fix indentation for the selected lines
`\ef`	Normal	Fix entire file (default `<Leader>ef` mapping)
`\ef`	Visual	Fix selected lines (default `<Leader>ef` mapping)

The plugin detects the language from the file extension -- .pm and .pl map to Perl, .xs to XS, .html to HTML, and so on. If the eshu binary is not in your $PATH, point the plugin at it:

let g:eshu_cmd = '/path/to/Eshu/bin/eshu'

To disable the default mappings and use your own:

let g:eshu_no_mappings = 1
nnoremap <silent> <F6> :EshuFix<CR>
vnoremap <silent> <F6> :EshuFixRange<CR>

Eshu is available on CPAN under the Artistic License 2.0.

Ready, Set, Compile... you slow Camel

LNATION — Sun, 25 Jan 2026 13:47:26 +0000

"Perl is slow."

I've heard this for years, well since I started. You probably have too. And honestly? For a long time, I didn't have a great rebuttal. Sure, Perl's fast enough for most things, it's well known for text processing, glueing code and quick scripts. But when it came to object heavy code, the critics have a point.

We will begin by looking at the myth of perl being slow a little more deeply. Here's a benchmark between Perl and Python using CPU seconds, a fair comparison that measures actual work done:

=== PERL (5 CPU seconds per test) ===
Integer arithmetic             1,072,800/s
Float arithmetic                 398,800/s
String concat                    970,000/s
Array push/iterate               368,800/s
Hash insert/iterate               84,800/s
Function calls                   244,000/s
Regex match                   12,921,200/s

=== PYTHON (5 CPU seconds per test) ===
Integer arithmetic               777,200/s
Float arithmetic                 512,400/s
String concat                    627,200/s
List append/iterate              476,400/s
Dict insert/iterate              140,600/s
Function calls                   331,400/s
Regex match                   10,543,713/s

The results are more nuanced than the "Perl is slow" narrative suggests:

Operation	Winner	Margin
Integer arithmetic	Perl	1.4x faster
Float arithmetic	Python	1.3x faster
String concat	Perl	1.5x faster
Array/List ops	Python	1.3x faster
Hash/Dict ops	Python	1.7x faster
Function calls	Python	1.4x faster
Regex match	Perl	1.2x faster

Perl wins at what it's always been good at: integers, strings, and regex. Python wins at floats, data structures, and function calls areas where I am told Python 3.x has seen heavy optimisation work.

But here's the thing that surprised me: neither language is dramatically faster than the other for basic operations. The differences are measured in fractions, not orders of magnitude. So where does the "Perl is slow" reputation actually come from?

Object-oriented code. Let's run that same fair comparison:

=== Object creation + 2 method calls (5M iterations) ===
Perl bless:    4,155,178/s  (1.20 sec)
Python class:  5,781,818/s  (0.86 sec)

Okay, this is not so bad. Perl's only 40% behind. But now let's look at what people actually use these days: Moo.

=== Object creation + 2 method calls (5M iterations) ===
Perl bless:    4,176,222/s  (1.20 sec)
Moo class:       843,708/s  (5.93 sec)
Python class:  5,590,052/s  (0.89 sec)

Wait, what? Moo is 6.6x slower than Python. And it's 5x slower than plain bless.

This is layered with actual business logic is I guess where "Perl is slow" actually comes from. This all comes down to layers. Every Moo accessor has been optimised but if you have all features you build a call stack, each adding overhead:

$obj->name
  └─> accessor method (generated sub)
        └─> type constraint check
              └─> coercion check
                    └─> trigger check
                          └─> lazy builder check
                                └─> finally: $self->{name}

Each of those subroutine calls means:

Push arguments onto the stack (~3-5 ops)
Create a new scope (localizing variables)
Execute the check (even if it's just "return true")
Pop the stack and return (~3-5 ops)

Even a "simple" Moo accessor with just a type constraint involves roughly 30+ additional operations compared to a plain hash access. The type constraint alone might call:

has_type_constraint() - is there a constraint?
type_constraint() - get the constraint object
check() - call the constraint's check method
The actual validation logic

Multiply that by two accessors per iteration, five million iterations, and suddenly you're spending 5 seconds instead of 1.

This is the trade off Moo makes: flexibility and safety for speed. And for most applications, it's the right trade off and even in python they do this with what they call pydantic that halfs the performance of python objects.

I've spent more time than I'd care to admit thinking about this question. Not in a "let's rewrite everything in Rust" kind of way, but genuinely asking: what would it take to make Perl's object system competitive with languages people actually consider fast?

The answer, it turns out, was inside a CPAN module first released on 'Mon Jul 24 11:23:25 2000'. This was highlighted to me by another works who I am indeed one of the three people who do not only read their blogs but also often finds themselves lost within their interesting coding patterns.

So this is the story of the four modules that changed how I think about Perl performance: Marlin, Meow, Inline and XS::JIT. They're different tools with different philosophies, but together they represent something I never quite expected to see Perl object access that's actually faster than Python's equivalent. Not "almost as fast." Faster.

The Marlin story: A faster fish in the Moose family

If you've written any serious Perl in the last fifteen years, you've probably used Moose. Or Moo. Or Mouse. The naming convention is... well, it's a thing we do now.

Marlin fits right into that tradition, and the name's not accidental. Marlins are among the fastest fish in the ocean. That's the pitch: everything you love about Moose-style OO, but with speed as a first-class concern.

Toby Inkster released Marlin in late 2025, and it caught my attention as I stated before, many of his projects do. I'd previously attempted to write a fast OO system myself (Meow), but was struggling to even compete with Moo despite being entirely XS. Partly ability, partly still learning, mostly not being in the right compile time stage.

With my interest piqued, I installed Marlin, played with the API, and ran some benchmarks:

Benchmark: 1,000,000 iterations
            Rate   Meow    Moo Marlin  Mouse
Meow    606,061/s     --    -1%   -45%   -47%
Moo     609,756/s     1%     --   -45%   -46%
Marlin 1,098,901/s    81%    80%     --    -3%
Mouse  1,136,364/s    87%    86%     3%     --

Marlin performed well. Meow at that point was... not impressive. But I liked Marlin's API and, understanding my own implementation's limitations, I was satisfied enough with the speed to build my Claude modules around it, while also understanding it would likely improve in performance.

A few weeks later, and a lot happened in between, but on Friday evening I randomly decided to revisit my Meow directory. Could I fix some of the flaws based upon my recent learnings? I managed to, and saw a huge improvement in my own benchmarks. So I updated to the latest Marlin for a fair comparison.

I was expecting Meow to be faster now since I'm doing much less in this minimalist approach. But what I actually found surprised me:

Benchmark: 10,000,000 iterations
            Rate    Moo  Mouse   Meow Marlin
Moo     868,810/s     --   -47%   -60%   -81%
Mouse  1,626,016/s    87%     --   -26%   -64%
Meow   2,183,406/s   151%    34%     --   -52%
Marlin 4,504,505/s   418%   177%   106%     --

Marlin had gotten dramatically faster, over 4x improvement from the version I'd first tested. Toby had clearly been busy. And while Meow had improved too, it was still only half of Marlin's speed.

This was the moment that changed everything. I needed to understand how Marlin achieved this. What was I missing?

Just in time optimisation

As I mentioned, I read other people's code. I read Toby's posts on Marlin and how he'd studied Mouse's optimisation strategy: only validate when you absolutely need to. But when I started tracing through Marlin's actual implementation, something clicked.

The key insight is in Marlin::Attribute::install_accessors. Here's what happens when Marlin sets up a reader:

if ( $type eq 'reader' and !$me->has_simple_reader and $me->xs_reader ) {
    $me->{_implementation}{$me->{$type}} = 'CXSR';  # Class::XSReader
}
elsif ( HAS_CXSA and $me->has_simple_reader ) {
    # Use Class::XSAccessor for simple cases
    Class::XSAccessor->import( class => $me->{package}, ... );
}

Marlin makes a compile-time decision: what kind of accessor does this attribute actually need?

Simple getter (no default, no lazy, no type check on read)? → Use Class::XSAccessor, which is pure XS and blindingly fast
Getter with lazy default or type coercion? → Use Class::XSReader, which handles the complexity in optimised C
Something exotic (auto_deref, custom behaviour)? → Fall back to generated Perl

This is the magic. Most Moo-style accessors go through a generic code path that handles every possible feature, even features you're not using. Marlin analyses your attribute definition at compile time and generates the minimal accessor that satisfies your requirements.

Consider a read-only attribute with a type but no default:

# Moo accessor path:
$obj->name
  → check if lazy builder needed     # nope, but we still check
  → check if default needed          # nope, but we still check  
  → check if coercion needed         # nope, but we still check
  → finally: $self->{name}

# Marlin accessor (Class::XSAccessor):
$obj->name
  → $self->{name}                    # that's it. One XS call.

The type constraint? Marlin validates it in the constructor, not the getter. Once an object is built, reading an attribute is just a hash lookup: no validation, no subroutine calls, no stack manipulation.

This is why Marlin went from 1.1M ops/sec to 4.5M ops/sec between versions. Toby wasn't just optimising code. He was eliminating entire categories of runtime work by moving decisions to compile time.

A different approach is used forClass::XSConstructor. This reuses a generic XSUB but passes the class data via a custom pointer. This sub is then optimised to not need to reach back into perl for stash, hv lookups etc.

It's JIT compilation, but done at module load time rather than runtime. By the time your code calls ->new or ->name, all the decisions have been made. All that's left is the actual work.

This was my revelation: the path to fast Perl OO isn't avoiding features, it's avoiding runtime feature detection. Know what you need at compile time, generate optimised code for exactly that, and get out of the way.

Now the question became: could I apply this same principle to Meow? It was already setup to build a simple hash that represented the object, I had what I needed but I wanted to do this in a backwards compatible way.

Enter Inline::C

Armed with the understanding of why Marlin was fast, I had a hypothesis: if I could generate XS accessors at compile time tailored to each attribute's needs, Meow could achieve the same performance.

I needed to generate custom C code and then execute it, well for perl that was written by Ingy döt Net back in 2000 the Inline::C.

The idea was simple: when Meow sees ro name => Str, it should generate C code for an accessor that:

Takes the object
Returns the value at the slot index for name
That's it. No method dispatch, no type checking, no feature checking.

I didn't want to just break everything so I leaned into the Moose catalog and added a make_immutable phase. When this is called it would compile the C code needed to generate an optimised XS package and this was fed into Inline::C. The first run would compile; subsequent runs would use the cached .so.

And it worked. I had to change the benchmark to CPU to get a fair result but I've also included a Cor test here which does not have type checking like Marlin or Meow.

Benchmark: running Cor, Marlin, Meow for at least 5 CPU seconds...
       Cor:  5 wallclock secs ( 5.13 usr +  0.02 sys =  5.15 CPU) @ 2,886,788/s
    Marlin:  5 wallclock secs ( 5.01 usr +  0.11 sys =  5.12 CPU) @ 4,523,074/s
      Meow:  5 wallclock secs ( 5.16 usr +  0.02 sys =  5.18 CPU) @ 4,558,344/s

As you can see Meow had caught Marlin. Actually, it was slightly faster, 4.56M vs 4.52M ops/sec, but this would be expected as Meow does ALOT less than Marlin.

But my bottlekneck was now in Inline::C and well nobody wants to write C/XS let alone concatenate it.

Startup overhead: First compilation was slow, several seconds for a complex class
Dependencies: Inline::C pulls in Parse::RecDescent, adds complexity to the dependency chain
Build process: It generates a full Makefile.PL and runs the ExtUtils::MakeMaker machinery
Caching: The caching mechanism is designed for "write once" scripts, not dynamic code generation

For a proof of concept, Inline::C was perfect. But for a production module, I needed something leaner. That's when I started looking at what Inline::C actually does under the hood, and wondering how much of it I could strip away.

Under the hood: XS::JIT as the secret weapon

Inline::C proved the concept worked, but it came with baggage. Every compile spawned a full Makefile.PL build process. Dependencies bloated the install. And the caching system, designed for write-once scripts, wasn't ideal for dynamic code generation.

So I started picking apart what Inline::C actually does:

Parse C code to find function signatures
Generate XS wrapper code
Generate a Makefile.PL
Run perl Makefile.PL && make
Load the resulting .so

And yes, this happens even when you use bind Inline C => ... instead of the use form. The bind keyword just defers compilation to runtime rather than compile time. It doesn't change what gets done, only when. You still get the full Parse::RecDescent parsing, the xsubpp processing, the MakeMaker dance. The only difference is whether it happens at use time or when bind is called.

Most of this was unnecessary for my use case. I didn't need function parsing, I already knew what functions I was generating. I didn't need XS wrappers, I was writing XS-native code directly. And I definitely didn't need the Makefile.PL dance.

XS::JIT strips all of that away. It's a single-purpose tool: take C code, compile it, load it, install the functions. No parsing. No xsubpp. No make. Direct compiler invocation.

Here's what the C API looks like:

#include "xs_jit.h"

/* Function mapping - where to install what */
XS_JIT_Func funcs[] = {
    { "Cat::new",  "cat_new",  0, 1 },  /* target, source, varargs, xs_native */
    { "Cat::name", "cat_name", 0, 1 },
    { "Cat::age",  "cat_age",  0, 1 },
};

/* Compile and install in one call */
int ok = xs_jit_compile(aTHX_
    c_code,           /* Your generated C code */
    "Meow::JIT::Cat", /* Unique name for caching */
    funcs,            /* Function mapping array */
    3,                /* Number of functions */
    "_CACHED_XS",     /* Cache directory */
    0                 /* Don't force recompile */
);

That's it. One function call. The first time it runs, XS::JIT:

Generates a boot function that registers all the XS functions
Compiles directly with the system compiler (cc -shared -fPIC ...)
Loads the .so with DynaLoader
Installs each function into its target namespace

Subsequent runs? It hashes the C code, finds the cached .so, and just loads it. The compile step vanishes entirely.

The key insight is the is_xs_native flag. When set, XS::JIT creates a simple alias: no wrapper function, no stack manipulation, no overhead. Your C function is the XS function:

XS_EUPXS(cat_name) {
    dVAR; dXSARGS;
    SV *self = ST(0);
    AV *av = (AV*)SvRV(self);
    SV **slot = av_fetch(av, 0, 0);  /* slot 0 = name */
    ST(0) = slot ? *slot : &PL_sv_undef;
    XSRETURN(1);
}

No wrapper. No intermediate calls.

This is exactly what Meow needed. During make_immutable, it:

Analyses each attribute's requirements (type constraint? coercion? trigger?)
Generates minimal XS accessor code for each one
Generates an optimised XS constructor that handles all attributes in one pass
Hands the code to XS::JIT for compilation
Gets back installed functions ready to call

The entire JIT compilation happens once per class, at module load time. By the time your code runs, everything is native XS.

Comparing the approaches

Here's what actually happens at runtime for each framework:

Moo accessor call:

$obj->name
  → Perl method dispatch
    → Generated Perl subroutine
      → has_type_constraint() check
        → type_constraint() fetch
          → check() call
            → finally: $self->{name}

Stack frames: 4-6. Operations: ~30.

Marlin accessor call (Class::XSAccessor):

$obj->name
  → Perl method dispatch
    → XS accessor
      → $self->{name}

Stack frames: 1. Operations: ~5.

Note: Toby has some slot magic also

Meow accessor call (XS::JIT):

$obj->name
  → Perl method dispatch
    → XS accessor
      → $self->[SLOT_INDEX]

Stack frames: 1. Operations: ~4 (arrays are slightly faster than hashes).

The benchmark results

With XS::JIT in place, here's where Meow now landed:

Benchmark: running Cor, Marlin for at least 5 CPU seconds... Marlin and Meow has type constraint checking
       Cor:  5 wallclock secs ( 5.13 usr +  0.02 sys =  5.15 CPU) @ 2886788.16/s (n=14866959)
    Marlin:  5 wallclock secs ( 5.01 usr +  0.11 sys =  5.12 CPU) @ 4523074.80/s (n=23158143)
      Meow:  5 wallclock secs ( 5.16 usr + -0.01 sys =  5.15 CPU) @ 5196218.06/s (n=26760523)
Benchmark: running Marlin, Meow, Moo, Mouse for at least 5 CPU seconds...
    Marlin:  5 wallclock secs ( 5.22 usr +  0.13 sys =  5.35 CPU) @ 4814728.04/s (n=25758795)
      Meow:  5 wallclock secs ( 5.23 usr +  0.01 sys =  5.24 CPU) @ 5203329.96/s (n=27265449)
       Moo:  4 wallclock secs ( 5.28 usr +  0.00 sys =  5.28 CPU) @ 860649.81/s (n=4544231)
     Mouse:  6 wallclock secs ( 5.29 usr +  0.01 sys =  5.30 CPU) @ 1603849.25/s (n=8500401)
            Rate    Moo  Mouse Marlin   Meow
Moo     860650/s     --   -46%   -82%   -83%
Mouse  1603849/s    86%     --   -67%   -69%
Marlin 4814728/s   459%   200%     --    -7%
Meow   5203330/s   505%   224%     8%     --

I must be honest, around this time I had not implemented the full benchmarks against Perl and Python. I didn't fully understand the difference, so I had some thoughts that I was hitting limitations with my own hardware (it was late, or early in the morning). Anyway, I kept pushing and ran a benchmark where I accessed the slot directly as an array reference. This got me excited:

Meow (direct) 7,172,481/s     778%    347%     50%     14%

I was seeing a huge improvement. I spent some time making an API that was a little nicer by exposing constants as slot indexes:

{
    package Cat 
    use Meow;
    ro name => Str;
    ro age => Int;
    make_immutable;  # Creates $Cat::NAME, $Cat::AGE
}

# Direct slot access
my $name = $cat->[$Cat::NAME];

I was now on par with Python, but I wanted more. There had to be a way to get that array access without the ugly syntax.

So I dug deeper into Perl's internals and found the missing magic: cv_set_call_checker and custom ops.

The entersub bypass: Custom ops

Here's what normally happens when you call a method in Perl:

name($cat)
  → OP_ENTERSUB (the "call function" op)
    → Push arguments onto stack
    → Look up the CV (code value)
    → Set up new stack frame
    → Execute the XS function
    → Pop stack frame
    → Return

Even for our minimal XS accessor, there's overhead: the entersub op itself, the stack frame setup, the CV lookup. What if we could eliminate all of that?

Perl provides a hook called cv_set_call_checker. It allows you to register a "call checker" function that runs at compile time when the parser sees a call to your subroutine. The checker can inspect the op tree and crucially replace it with something else entirely.

Here's what Meow does:

static void _register_inline_accessor(pTHX_ CV *cv, IV slot_index, int is_ro) {
    SV *ckobj = newSViv(slot_index);  /* Store slot index for later */
    cv_set_call_checker_flags(cv, S_ck_meow_get, ckobj, 0);
}

When the checker sees name($cat), it:

Extracts the $cat argument from the op tree
Frees the entire entersub operation
Creates a new custom op with the slot index baked in
Returns that instead

The custom op is trivially simple:

static OP *S_pp_meow_get(pTHX) {
    dSP;
    SV *self = TOPs;
    PADOFFSET slot_index = PL_op->op_targ;  /* Baked into the op */

    SV **ary = AvARRAY((AV*)SvRV(self));
    SETs(ary[slot_index] ? ary[slot_index] : &PL_sv_undef);

    return NORMAL;
}

That's the entire accessor. No function call. No stack frame. No CV lookup. The slot index is embedded directly in the op structure. The Perl runloop executes this op directly, it's as close to $cat->[$NAME] as you can get while still looking like name($cat).

This is the same technique that builtin::true and builtin::false use in Perl 5.36+. It's also how List::Util::first can be optimised when given a simple block.

The final benchmark

With custom ops in place via import_accessors, here's how the Perl OO frameworks compare:

Benchmark: running Marlin, Meow, Meow (direct), Meow (op), Moo, Mouse for at least 5 CPU seconds...
    Marlin:  6 wallclock secs ( 5.09 usr +  0.11 sys =  5.20 CPU) @ 4766685.58/s (n=24786765)
      Meow:  5 wallclock secs ( 5.29 usr +  0.01 sys =  5.30 CPU) @ 6289606.79/s (n=33334916)
Meow (direct):  5 wallclock secs ( 5.32 usr +  0.01 sys =  5.33 CPU) @ 7172480.86/s (n=38229323)
 Meow (op):  5 wallclock secs ( 5.16 usr +  0.01 sys =  5.17 CPU) @ 7394453.19/s (n=38229323)
       Moo:  4 wallclock secs ( 5.44 usr +  0.02 sys =  5.46 CPU) @ 816865.93/s (n=4460088)
     Mouse:  4 wallclock secs ( 5.18 usr +  0.01 sys =  5.19 CPU) @ 1605727.55/s (n=8333726)
                   Rate      Moo   Mouse  Marlin    Meow Meow (direct) Meow (op)
Moo            816866/s       --    -49%    -83%    -87%          -89%      -89%
Mouse         1605728/s      97%      --    -66%    -74%          -78%      -78%
Marlin        4766686/s     484%    197%      --    -24%          -34%      -36%
Meow          6289607/s     670%    292%     32%      --          -12%      -15%
Meow (direct) 7172481/s     778%    347%     50%     14%            --       -3%
Meow (op)     7394453/s     805%    361%     55%     18%            3%        --

Now lets test that directly against python:

============================================================
Python Direct Benchmark (slots + property accessors)
============================================================
Python version: 3.9.6 (default, Dec  2 2025, 07:27:58)
[Clang 17.0.0 (clang-1700.6.3.2)]
Iterations: 5,000,000
Runs: 5
------------------------------------------------------------
Run 1: 0.649s (7,704,306/s)
Run 2: 0.647s (7,733,902/s)
Run 3: 0.646s (7,736,307/s)
Run 4: 0.648s (7,720,909/s)
Run 5: 0.649s (7,702,520/s)
------------------------------------------------------------
Median rate: 7,720,909/s
============================================================
============================================================
Perl/Meow Benchmark Comparison
============================================================
Perl version: 5.042000
Iterations: 5000000
Runs: 5
------------------------------------------------------------
Inline Op (one($foo)):
  Run 1: 0.638s (7,841,811/s)
  Run 2: 0.629s (7,954,031/s)
  Run 3: 0.631s (7,929,850/s)
  Run 4: 0.631s (7,926,316/s)
  Run 5: 0.633s (7,901,675/s)
  Median: 7,926,316/s
============================================================
Summary:
------------------------------------------------------------
  Inline Op:    7,926,316/s
============================================================

Conclusion: Why JIT might be the right approach

Looking back at this journey, a pattern emerges. The fastest code isn't the cleverest code. It's the code that does the least work at runtime.

Moo is slow because of the abstraction.

Marlin proved that you could have Moo's features without Moo's overhead by making smart choices at compile time. If an accessor doesn't need lazy building, don't generate code that checks for lazy building.

Meow pushed this further: if you're going to generate code at compile time anyway, why not generate exactly the code you need? Not a generic accessor that handles many cases, but a specific accessor for this specific attribute on this specific class.

And XS::JIT made that practical. Without a lightweight JIT compiler, dynamic XS generation would require shipping a C toolchain with every module, or adding multi-megabyte dependencies. XS::JIT strips the problem down to its essence: take C code, compile it, load it.

The result is object access that competes with, and sometimes beats, languages that have had decades of optimisation work. Not because Perl's interpreter got faster, but because we stopped asking it to do unnecessary work.

Is this approach right for every project? No. Most applications don't need 7 million object accesses per second.

But for the times when performance matters (hot loops, high-frequency trading, real-time systems) it's good to know the ceiling isn't as low as we thought. Perl can be fast. We just needed to get out of its way.

The modules discussed in this post:

Marlin: https://metacpan.org/pod/Marlin
Meow: https://metacpan.org/pod/Meow
XS::JIT: https://metacpan.org/pod/XS::JIT
Inline::C: https://metacpan.org/pod/Inline::C

Doubly: Why Arrays Aren't Always Enough

LNATION — Sun, 18 Jan 2026 18:28:08 +0000

As most of you reading this will know, Perl has three core data types: scalars, arrays, and hashes. They're relatively fast, they're familiar, and for most tasks, they just work. But sometimes you need something more.

A while back, I started at a new company and had a conversation with a colleague. They'd been working on a certain part of the codebase where the bottleneck was a pure Perl implementation of a doubly linked list. I knew of the concept and would usually just use an array for this task. They were adamant this could not work with an array though, so I inspected the code to understand the use case.

My initial gut instinct and others on IRC after I had published the first version, was why not just use an array, well.. if you take this example

my @playlist = ('song_a', 'song_b', 'song_c');
my $current = 1;  # pointing at 'song_b'

# Move forward
$current++ if $current < $#playlist;

# Insert after current position? Now things get messy.
splice(@playlist, $current + 1, 0, 'new_song');

Every insertion is O(n) because Perl has to shift elements. Your index can become stale if you're not careful. And if you're working with threads or nested data? Good luck keeping that index synchronised. Also just wrapping this in a module does not work the moment you add insertion.

This launched me on a journey that would eventually produce four different doubly linked list implementations, each one teaching me something new about Perl, XS, C, and the fascinating trade offs between simplicity, speed, and safety. This journey spanned several months and it was 'Claude' opus who helped me come to the final solution which is thread safe and has no memory leakage.

Cursor Based Navigation vs Indexed Access

Before diving into the advantages, let's establish what a doubly linked list actually is. Unlike an array where elements sit in contiguous memory slots accessed by index, a doubly linked list is a chain of nodes. Each node contains three things: your data, a pointer to the next node, and a pointer to the previous node. This bidirectional linking is what puts the "doubly" in doubly linked list.

┌──────────┐    ┌──────────┐    ┌──────────┐
│   prev ←─┼────┼─ prev ←──┼────┼─ prev    │
│  'intro' │    │  'verse' │    │ 'chorus' │
│   next ──┼────┼→ next ───┼────┼→ next    │
└──────────┘    └──────────┘    └──────────┘

Beyond the basic node structure, a well designed doubly linked list maintains a current position—an internal cursor that tracks where you are in the list. This changes everything about how you interact with your data.

Navigation methods like next(), prev(), start(), and end() move this internal cursor, and data() operates on whatever node you're currently pointing at.

Here's what that looks like in practice:

use Doubly;

my $playlist = Doubly->new();
$playlist->add('intro.mp3')
         ->add('verse.mp3')
         ->add('chorus.mp3')
         ->add('outro.mp3');

# Navigate with the cursor
$playlist->start();           # cursor at 'intro.mp3'
$playlist->next();            # cursor at 'verse.mp3'
print $playlist->data();      # prints 'verse.mp3'

$playlist->next()->next();    # method chaining! cursor at 'outro.mp3'
$playlist->prev();            # back to 'chorus.mp3'

Compare this to the array approach where you're juggling data and position separately:

my @playlist = ('intro.mp3', 'verse.mp3', 'chorus.mp3', 'outro.mp3');
my $pos = 0;

$pos++;
print $playlist[$pos];  # 'verse.mp3'

$pos += 2;
$pos--;

The array version works, but you're managing two things instead of one. The index is disconnected from the data. Pass that array to a function and the position doesn't follow, you'd need to pass both.

But here's where it gets really interesting: nested lists with shared position tracking.

When you store a Doubly list inside another Doubly list, something magical happens. The inner list maintains its own cursor, and every time you access it, you get the same object with its position preserved:

my $outer = Doubly->new();
my $inner = Doubly->new();

$inner->add('a')->add('b')->add('c');
$outer->add($inner);

$outer->start();
my $nested = $outer->data();    # get the inner list
$nested->start()->next();        # move inner cursor to 'b'

# Later...
my $same_nested = $outer->data();  # same object!
print $same_nested->data();         # still at 'b'!

This shared position tracking is incredibly powerful for hierarchical data. Think of a file browser where each directory remembers which file you last selected, or a document editor where each section remembers your scroll position.

The cursor based model also makes certain algorithms beautifully clean. Need to process items around your current position? No index arithmetic required:

# Insert after current position - O(1)!
$list->insert_after('new_item');

# Remove current and move to next
$list->remove();

# Check boundaries naturally
while (!$list->is_end()) {
    process($list->data());
    $list->next();
}

With arrays, insert_after at position n means splice(@arr, $n + 1, 0, $item)—and that's an O(n) operation that shifts every subsequent element. The doubly linked list just adjusts a few pointers.

Also with a doubly linked list when you attain a reference to the data, that reference remains the same. If you were to use a plain perl object to track your state that reference will either change on iteration or become stale if you clone.

This cursor based navigation is what makes doubly linked lists shine for the use cases my colleague was struggling with. It's not just about performance—it's about expressing your intent clearly and letting the data structure handle the bookkeeping.

From Hash Nodes to C Registries

Now let's look under the hood at how each implementation actually works.

Doubly::Linked::PP — Pure Perl Simplicity

The pure Perl implementation is the most transparent. Each node is a blessed hash reference with three keys:

my $node = bless {
    data => 'my_value',
    next => $next_node,  # reference to next node (or undef)
    prev => $prev_node,  # reference to previous node (or undef)
}, 'Doubly::Linked::PP';

The list object itself tracks head, tail, current. Every operation is pure Perl hash manipulation:

sub next {
    my ($self) = @_;
    if ($self->{current} && $self->{current}->{next}) {
        $self->{current} = $self->{current}->{next};
    }
    return $self;
}

This approach has huge advantages: no compilation required, fully debuggable with Data::Dumper, and runs anywhere Perl runs. You can literally inspect the entire structure at any time:

use Data::Dumper;
print Dumper($list);  # see everything!

The downside? At 769 ops/sec, it's not winning any races. Every method call goes through Perl's method dispatch. Every hash access is a hash lookup. And there's a subtler problem: circular references. Node A's next points to Node B, and Node B's prev points back to Node A. Perl's reference counting garbage collector can't automatically clean these up—you need to manually break the cycle or use weak references, otherwise you're leaking memory. The overhead adds up fast.

Doubly::Linked — XS with Perl Structures

The next step was Doubly::Linked, which uses XS (Perl's interface to C) but still constructs Perl hash structures. The C code builds the same {data, next, prev} hashes, just faster:

// Simplified from Doubly::Linked XS
HV* node = newHV();
hv_store(node, "data", 4, newSVpv(data, 0), 0);
hv_store(node, "next", 4, next_sv, 0);
hv_store(node, "prev", 4, prev_sv, 0);

This gives you compiled C speed for node creation and manipulation, whilst keeping the familiar Perl hash structure. You still get that Data::Dumper visibility.

Performance jumped to about 1,020 ops/sec in non threaded Perl roughly 1.3x faster than pure Perl. Respectable, but I knew we could do better. The problem is that we're still paying for Perl's hash overhead on every single operation.

Doubly::Pointer — Raw C Pointers

Here's where things get fast. Doubly::Pointer abandons Perl structures entirely and uses pure C:

typedef struct Node {
    SV* data;           // Perl scalar value
    struct Node* next;  // C pointer
    struct Node* prev;  // C pointer
} Node;

typedef struct {
    Node* head;
    Node* tail;
    Node* current;
    int length;
} DoublyList;

The Perl object is just a thin wrapper around a C pointer. No hashes, no Perl data structure overhead just raw memory and pointer arithmetic.

The result? 12,987 ops/sec. That's nearly 17x faster than pure Perl! Navigation is just pointer dereferencing. Insertion is just reassigning a couple of pointers. This is as fast as it gets in Perl land.

I released these three in quick succession and was happy with the performance boost of the Doubly implementation but it had some flaws. Mainly it was leaking memory, I asked on IRC for help but none was provided so I left the module for a while..

Then: Enter Claude

After letting the module sit for several months with its memory leaks, as we all know llm has gradually been getting better at code generation and debugging so I decided to revisit it with the help of Opus. What followed was an intensive collaboration that transformed my understanding of the problem.

Claude helped me trace through the reference counting issues, understand where my SvREFCNT_inc and SvREFCNT_dec calls were mismatched, and ultimately architect the registry based solution that would become Doubly. The breakthrough wasn't just fixing the leaks, it was realising that the entire pointer in Perl object approach was fundamentally flawed for threaded environments.

So the problem is that raw pointers becomes ticking time bombs in threaded code. When Perl clones an object across threads, it copies the pointer value. But that pointer address is only valid in the original thread's memory space. Access it from another thread and you get crashes, corruption, or worse... silent data mangling.

For single threaded applications, the old Doubly now Doubly::Pointer is fine. But I wanted something that could handle threads safely.

Doubly — The Thread Safe Registry

So with Claude's teachings, this is where it all came together. Doubly achieves thread safety through an architectural shift: instead of storing C pointers in Perl objects, it uses a global registry with integer IDs.

#define MAX_LISTS 65536

static DoublyList* registry[MAX_LISTS];
static int registry_ids[MAX_LISTS];
static perl_mutex registry_mutex;

The Perl object stores just an integer ID and a stable node ID. When you call any method, the XS code:

Locks the mutex
Looks up the list by ID in the registry
Finds the node by its unique _node_id
Performs the operation
Unlocks the mutex

// Lookup is O(1) - just array indexing
static DoublyList* _get_list(int id) {
    if (id < 0 || id >= MAX_LISTS) {
        return NULL;
    }
    return list_registry[id];
}

// Each operation wraps with locking:
SHARED_LOCK();
list = _get_list(id);
// ... perform operation ...
SHARED_UNLOCK();

The _node_id is stored per-object in Perl, so multiple references to the same list can point to different nodes, useful when different parts of your code need to track different positions simultaneously. Unlike position based indices, node IDs are stable: if you save a reference to a node and then insert or delete elsewhere in the list, your reference remains valid. This was a key architectural improvement that solved subtle bugs with an earlier position based approach, the same bugs you find with using just Arrays and a index.

For storing Perl references (hashes, arrays, objects), which is not simple for the same reasons as the pointers, Doubly uses threads::shared::shared_clone to create thread safe copies:

# When you do this in threaded Perl:
$list->add({ name => 'test', values => [1, 2, 3] });

# Doubly internally does:
my $shared = threads::shared::shared_clone($data);
# Then stores a reference ID to retrieve it later

We could not figure out how to do this in directly in the C/XS, so had to implement light callback hooks in the perl namespace, but it works perfectly.

The performance impact? In non threaded Perl, Doubly runs at 14,085 ops/sec, about 8% faster than Doubly::Pointer's 12,987 ops/sec. In threaded Perl, it performs similarly at 14,286 ops/sec versus 14,184 ops/sec. The registry architecture optimises surprisingly well. The integer to pointer lookup is O(1). You get nearly all the speed of raw pointers with none of the thread safety nightmares.

The threads::shared::shared_clone call is made directly from XS using Perl's call_pv() mechanism, but we needed light Perl-side helpers (_xs_store_ref, _xs_get_ref, _xs_clear_ref) for storing and retrieving from the shared hash—shared data structures require Perl-side assignment to work correctly with Perl's threading model.

So after all this, four implementations, countless hours of debugging segfaults, and deep dives into XS and mutex locks. When should you actually reach for a doubly linked list instead of a trusty array?

Choose Doubly Lists When:

You need O(1) insertions and deletions in the middle of your data. Arrays make you pay O(n) for every splice. If you're building an editor buffer, a task queue with priorities, or anything where items frequently enter and leave from arbitrary positions, doubly linked lists win decisively.

Your algorithm thinks in terms of "current position." Undo/redo systems, playlist navigators, browser history, paginated views. These all have an inherent notion of "where am I?" that maps perfectly to cursor based navigation. Fighting against this with index tracking is unnecessary complexity.

You need bidirectional traversal. Moving forward and backward through data is natural with next() and prev(). With arrays, you're doing index arithmetic and bounds checking manually.

Thread safety matters. If there's any chance your code will run in a threaded environment, Doubly's registry architecture handles it transparently. No locks to manage, no race conditions to debug.

You're storing nested structures with independent navigation state. This is Doubly's secret weapon, inner lists maintain their own cursor position. Try implementing that cleanly with arrays.

Give doubly linked lists a try the next time you catch yourself wrestling with array indices and splice operations. You might be surprised how naturally some problems fit the cursor based model. And if you find yourself needing threads? You'll be glad you chose Doubly from the start.

Happy coding and may your pointers always be valid!

https://metacpan.org/pod/Doubly

The Perl Claude Agent

LNATION — Sun, 11 Jan 2026 07:51:00 +0000

So over the past few days I've built a new addition to the Perl ecosystem: the Claude Agent SDK. It's a library that brings the agentic capabilities of Claude Code into your Perl applications.

At its core, the SDK enables you to build AI agents that can read files, run shell commands, search the web, edit code, and interact with external systems. All orchestrated from familiar Perl code. Whether you're automating code reviews, building intelligent DevOps tooling, or integrating AI capabilities into legacy systems, this SDK provides the foundation you need.

The architecture is built around a streaming JSON Lines protocol (using my JSON::Lines module) that communicates with the Claude Code CLI, supporting both synchronous operations and fully asynchronous patterns via IO::Async and Future::AsyncAwait. Although we send valid JSON lines, the CLI doesn't always return valid JSON lines, so some extension to my module was needed to handle malformed responses gracefully. Here's what a simple interaction looks like:

use Claude::Agent qw(query);
use Claude::Agent::Options;

my $options = Claude::Agent::Options->new(
    allowed_tools   => ['Read', 'Glob', 'Grep'],
    permission_mode => 'bypassPermissions',
);

my $iter = query(
    prompt  => "What files in ./lib need the most refactoring?",
    options => $options,
);

while (my $msg = $iter->next) {
    if ($msg->isa('Claude::Agent::Message::Result')) {
        print $msg->result;
        last;
    }
}

The real power emerges when you explore the SDK's advanced features: custom MCP tools that can run directly in your Perl process with full access to your application state, a subagent system for spawning specialised AI workers with isolated contexts, session management for resuming or forking conversations, and structured output with JSON Schema validation for automation-ready responses.

The SDK is complemented by two separate distributions I wrote that showcase what's possible: a Code Review module for AI-powered analysis with severity-based issue detection and Perlcritic integration, and a Code Refactor module that implements an automated review-fix-repeat loop until your codebase is clean.

Let's dive into how it all works.

Custom MCP Tools That Run in Your Process

One of the most powerful features of the Claude Agent SDK is the ability to create custom MCP tools that execute directly in your Perl process. Unlike external MCP servers that run as separate services, SDK tools have full access to your application's state: your database connections, configuration, session data, and any Perl modules you're already using.

This architecture enables significant functional extensibility. To permit Claude to execute queries against production databases, retrieve customer records, or access inventory data, these operations can be exposed as callable tools within the conversational interface. All tool invocations adhere to JSON Schema validation, ensuring type safety and structural integrity throughout the execution pipeline.

You define a tool with four components: a name, a description (which helps Claude understand when to use it), an input schema (JSON Schema defining the parameters), and a handler (your Perl code that does the actual work):

use Claude::Agent qw(tool create_sdk_mcp_server);

my $find_user = tool(
    'find_user',                              # Tool name
    'Find a user by their email address',    # Description for Claude
    {                                         # JSON Schema for inputs
        type       => 'object',
        properties => {
            email => {
                type        => 'string',
                description => 'Email address to search for'
            },
        },
        required => ['email'],
    },
    sub {                                     # Handler (runs in your process!)
        my ($args) = @_;
        # Your code here with full access to application state
        return {
            content => [{ type => 'text', text => 'Result goes here' }],
        };
    }
);

The magic is in that handler. It's not running in some sandboxed external process. It's running right in your Perl application, with access to everything you've already set up. Let's build a complete database query tool to see this in action:

#!/usr/bin/env perl
use 5.020;
use strict;
use warnings;

use Claude::Agent qw(query tool create_sdk_mcp_server);
use Claude::Agent::Options;
use IO::Async::Loop;
use DBI;

# Your existing database connection. The tool handler can use this directly
my $dbh = DBI->connect(
    'dbi:SQLite:customers.db',
    '', '',
    { RaiseError => 1, AutoCommit => 1 }
);

# Tool 1: Find a customer by email
my $find_customer = tool(
    'find_customer',
    'Look up a customer record by email address. Returns their name, plan, and signup date.',
    {
        type       => 'object',
        properties => {
            email => {
                type        => 'string',
                description => 'Customer email to search for'
            },
        },
        required => ['email'],
    },
    sub {
        my ($args) = @_;

        # Direct database access with no external API, no serialisation overhead
        my $customer = $dbh->selectrow_hashref(
            'SELECT name, email, plan, created_at FROM customers WHERE email = ?',
            undef,
            $args->{email}
        );

        if ($customer) {
            return {
                content => [{
                    type => 'text',
                    text => sprintf(
                        "Found customer: %s <%s>\nPlan: %s\nMember since: %s",
                        $customer->{name},
                        $customer->{email},
                        $customer->{plan},
                        $customer->{created_at}
                    ),
                }],
            };
        }

        return {
            content => [{
                type => 'text',
                text => "No customer found with email: $args->{email}"
            }],
        };
    }
);

# Tool 2: Get aggregate statistics
my $customer_stats = tool(
    'customer_stats',
    'Get statistics about customers, optionally filtered by plan type',
    {
        type       => 'object',
        properties => {
            plan => {
                type        => 'string',
                enum        => ['free', 'pro', 'enterprise'],
                description => 'Filter by plan type (optional)'
            },
        },
        required => [],  # No required params so Claude can call this with no arguments
    },
    sub {
        my ($args) = @_;

        my ($sql, @bind);
        if ($args->{plan}) {
            $sql = 'SELECT COUNT(*) as count, plan FROM customers WHERE plan = ? GROUP BY plan';
            @bind = ($args->{plan});
        } else {
            $sql = 'SELECT COUNT(*) as count, plan FROM customers GROUP BY plan ORDER BY count DESC';
        }

        my $rows = $dbh->selectall_arrayref($sql, { Slice => {} }, @bind);

        my @lines = map { "$_->{plan}: $_->{count} customers" } @$rows;
        return {
            content => [{
                type => 'text',
                text => join("\n", @lines) || "No customers found"
            }],
        };
    }
);

Now bundle these tools into an SDK MCP server and use them in a query:

# Create the MCP server
my $server = create_sdk_mcp_server(
    name    => 'customerdb',
    tools   => [$find_customer, $customer_stats],
    version => '1.0.0',
);

# Configure the agent to use our tools
my $options = Claude::Agent::Options->new(
    mcp_servers     => { customerdb => $server },
    allowed_tools   => $server->tool_names,  # ['mcp__customerdb__find_customer', ...]
    permission_mode => 'bypassPermissions',
    max_turns       => 10,
);

# Now Claude can query your database naturally
my $loop = IO::Async::Loop->new;
my $iter = query(
    prompt  => 'How many customers do we have on each plan? ' .
               'Also, look up the customer with email alice@example.com',
    options => $options,
    loop    => $loop,
);

# Stream the response
while (my $msg = $iter->next) {
    if ($msg->isa('Claude::Agent::Message::Assistant')) {
        for my $block ($msg->content_blocks) {
            print $block->text if $block->isa('Claude::Agent::Content::Text');
        }
    }
    elsif ($msg->isa('Claude::Agent::Message::Result')) {
        print "\n\nQuery complete.\n";
        last;
    }
}

When you run this, Claude will intelligently call both tools to answer your question. It might first call customer_stats with no arguments to get the plan breakdown, then call find_customer with email => 'alice@example.com' to look up that specific record. You'll see output like:

Let me check our customer data for you.

We have the following customers by plan:
- pro: 1,247 customers
- free: 3,892 customers
- enterprise: 89 customers

For alice@example.com, I found:
- Name: Alice Chen
- Plan: enterprise
- Member since: 2024-03-15

Behind the scenes, the SDK creates a Unix socket for communication between your main process and a lightweight MCP protocol handler. When Claude calls a tool, the request flows through the socket to your handler, which executes synchronously with full access to $dbh and any other state in scope. The result flows back to Claude, and the conversation continues.

This pattern is incredibly useful for building AI-powered interfaces to your existing systems. You're not building a new API. You're exposing capabilities that your Perl code already has, with Claude handling the natural language understanding and your handlers doing the actual work. The JSON Schema validation ensures Claude passes the right parameters, and your handlers can return structured results or friendly error messages.

A few things to note about handler implementation:

Return structure: Always return a hashref with a content array. Each element should have type => 'text' and a text field.
Error handling: Set is_error => 1 in your return value when something goes wrong. Claude will understand the operation failed.
Input validation: The SDK validates inputs against your JSON Schema, but you may want additional business logic validation in your handler.
Security: Be thoughtful about what you expose. The enum constraint in customer_stats limits which plans can be queried. You can use similar patterns to restrict what data Claude can access.

The Hook System for Fine-Grained Control

When you're running AI agents in production, you need visibility. What tools is Claude calling? With what parameters? How long did each operation take? Did anything get blocked? The Claude Agent SDK's hook system gives you complete control over the agent's tool execution lifecycle, letting you intercept, inspect, modify, or block any operation.

Think of hooks as middleware for AI agent operations. Every time Claude wants to call a tool, whether it's reading a file, running a bash command, or calling one of your custom MCP tools: your hooks get first dibs. You can log the operation, check it against security policies, modify the parameters, or shut it down entirely. And you get hooks for multiple lifecycle points: before execution, after success, after failure, and more.

The system is built around matchers that bind patterns to callbacks:

use Claude::Agent::Hook::Matcher;
use Claude::Agent::Hook::Result;

my $matcher = Claude::Agent::Hook::Matcher->new(
    matcher => 'Bash',           # Tool name pattern (regex or exact match)
    timeout => 60,               # Hook execution timeout in seconds
    hooks   => [                 # Array of callback subroutines
        sub {
            my ($input, $tool_use_id, $context) = @_;
            # Your logic here
            return Claude::Agent::Hook::Result->proceed();
        },
    ],
);

Each hook callback receives three arguments: $input (a hashref with tool_name and tool_input), $tool_use_id (a unique identifier for this specific invocation), and $context (a Claude::Agent::Hook::Context object with session metadata like session_id and cwd).

Your hooks return decisions using the Claude::Agent::Hook::Result factory:

# Let the operation proceed unchanged
return Claude::Agent::Hook::Result->proceed();

# Allow but modify the input parameters
return Claude::Agent::Hook::Result->allow(
    updated_input => { command => 'sanitized_command' },
    reason        => 'Modified for security',
);

# Block the operation entirely
return Claude::Agent::Hook::Result->deny(
    reason => 'This operation violates security policy',
);

The available hook events cover the tool execution lifecycle:

Event	When It Fires
`PreToolUse`	Before any tool executes
`PostToolUse`	After a tool completes successfully
`PostToolUseFailure`	After a tool fails

These three events are the workhorses of the hook system, giving you complete visibility into tool execution. The SDK also defines additional event types (SessionStart, SessionEnd, SubagentStart, SubagentStop, PermissionRequest, Notification, Stop, PreCompact, UserPromptSubmit) that cover session lifecycle, subagent management, and user interactions.

# Security hook, only fires for Bash tool
my $bash_security = Claude::Agent::Hook::Matcher->new(
    matcher => 'Bash',  # Exact match on tool name
    hooks   => [sub {
        my ($input, $tool_use_id, $context) = @_;

        my $command = $input->{tool_input}{command} // '';

        # Define blocked patterns
        my @dangerous_patterns = (
            qr/\brm\s+-rf\s+[\/~]/,      # rm,rf against root or home
            qr/\bsudo\b/,                 # No sudo commands
            qr/\bchmod\s+777\b/,          # World-writable permissions
            qr/>\s*\/etc\//,              # Redirecting to /etc
            qr/\bcurl\b.*\|\s*\bbash\b/,  # Piping curl to bash
            qr/\beval\b/,                 # Command eval
        );

        for my $pattern (@dangerous_patterns) {
            if ($command =~ $pattern) {
                write_audit_log({
                    timestamp   => scalar(gmtime) . ' UTC',
                    event       => 'TOOL_BLOCKED',
                    tool_use_id => $tool_use_id,
                    tool_name   => 'Bash',
                    reason      => 'Matched dangerous pattern',
                    pattern     => "$pattern",
                    severity    => 'CRITICAL',
                });

                return Claude::Agent::Hook::Result->deny(
                    reason => 'This command has been blocked by security policy.',
                );
            }
        }

        return Claude::Agent::Hook::Result->proceed();
    }],
);

Hook execution order matters. When you provide multiple matchers for the same event, they run in array order. Within a single matcher, if any hook returns allow or deny, subsequent hooks in that matcher don't execute. The decision is final.
Matcher patterns are flexible. Use an exact string like 'Bash' to match a specific tool, a regex pattern like 'mcp__.*' to match all MCP tools, or omit the matcher entirely to catch everything. The SDK includes ReDoS protection to prevent pathological regex patterns from hanging your process.
Hooks are exception-safe. If your callback throws, the SDK catches it and returns { decision => 'error' }. Your agent keeps running, and you can enable CLAUDE_AGENT_DEBUG=1 to see the full stack trace.
The context object is your friend. The $context parameter gives you the session ID (essential for correlating logs across a conversation), the current working directory, and the tool details. Use this metadata to make intelligent decisions about what to allow.

Subagents for Specialised Tasks

Sometimes a single agent isn't enough. Maybe you need to run multiple analyses in parallel, checking for security vulnerabilities while simultaneously reviewing code style. Maybe you want to isolate a complex task so it doesn't pollute your main conversation context. Or maybe you need specialised expertise: one agent focused purely on security, another on performance, each with tailored instructions and tool access.

This is what subagents are for. The Claude Agent SDK lets you define specialised agent profiles that your main agent can spawn on demand. Each subagent runs in its own isolated context with its own system prompt, tool permissions, and even model selection. Think of them as expert consultants your agent can call in when it needs help.

The architecture is elegant. You define subagents as configuration objects with four properties:

use Claude::Agent::Subagent;

my $subagent = Claude::Agent::Subagent->new(
    description => '...',   # When should Claude use this agent?
    prompt      => '...',   # System prompt defining expertise
    tools       => [...],   # Allowed tools (optional, inherits if not set)
    model       => '...',   # Model override (optional, 'sonnet', 'opus', 'haiku')
);

The description is key. Claude uses this to decide when to delegate. Write it like you're explaining to a colleague: "Expert security reviewer for vulnerability analysis" tells Claude exactly what this agent does. The prompt is the system prompt that shapes the subagent's behaviour, giving it the specialised knowledge and instructions it needs.

The subagent architecture provides several powerful capabilities:

Context isolation. Each subagent starts fresh with only its system prompt. There is no accumulated context from earlier in the conversation. This prevents context pollution and keeps analyses focused.

Tool restriction. Notice how secrets_detector doesn't have Bash access. It can only read files. This is defense in depth: even if the AI were to malfunction, a secrets-scanning agent physically cannot execute commands.

Model selection. Use Opus for complex security analysis where you need the strongest reasoning. Use Haiku for straightforward pattern-matching tasks. Your main agent can be Sonnet as the orchestrator. This optimises both cost and capability.

Parallel potential. While Claude currently executes subagents sequentially, the architecture supports parallel execution. When you spawn multiple subagents, their isolated contexts mean results can be combined without interference.

Async Tool Handlers

For tools that perform I/O operations—HTTP requests, database queries, file operations—blocking the event loop is wasteful. The SDK supports async tool handlers that return Futures, enabling true non-blocking execution.

Your handler receives the IO::Async::Loop as its second parameter. Use it to perform async operations and return a Future that resolves with your result:

use Future::AsyncAwait;
use Net::Async::HTTP;

my $fetch_url = tool(
    'fetch_url',
    'Fetch content from a URL asynchronously',
    {
        type       => 'object',
        properties => {
            url => { type => 'string', description => 'URL to fetch' },
        },
        required => ['url'],
    },
    async sub {
        my ($args, $loop) = @_;

        my $http = Net::Async::HTTP->new;
        $loop->add($http);

        my $response = await $http->GET($args->{url});

        return {
            content => [{
                type => 'text',
                text => sprintf("Status: %d\nBody: %s",
                    $response->code,
                    substr($response->decoded_content, 0, 1000)),
            }],
        };
    }
);

The same pattern works for hooks. Your hook callback can return a Future for async validation:

my $async_security_hook = Claude::Agent::Hook::Matcher->new(
    matcher => '.*',
    hooks   => [
        async sub {
            my ($input, $tool_use_id, $context, $loop) = @_;

            # Async check against a security policy service
            my $http = Net::Async::HTTP->new;
            $loop->add($http);

            my $resp = await $http->POST(
                'https://security.internal/check',
                content => encode_json($input),
            );

            if ($resp->code == 403) {
                return Claude::Agent::Hook::Result->deny(
                    reason => 'Blocked by security policy',
                );
            }

            return Claude::Agent::Hook::Result->proceed();
        },
    ],
);

One powerful pattern enabled by the shared event loop: spawning nested queries from within a tool handler. Your tool can invoke Claude as a sub-agent:

my $research_tool = tool(
    'deep_research',
    'Spawn a sub-agent to research a topic',
    {
        type       => 'object',
        properties => {
            topic => { type => 'string' },
        },
        required => ['topic'],
    },
    sub {
        my ($args, $loop) = @_;

        # Spawn a sub-query using the shared event loop
        my $sub_query = query(
            prompt  => "Research thoroughly: $args->{topic}",
            options => Claude::Agent::Options->new(
                allowed_tools   => ['Read', 'Glob', 'WebSearch'],
                permission_mode => 'bypassPermissions',
                max_turns       => 5,
            ),
            loop => $loop,
        );

        my $result = '';
        while (my $msg = $sub_query->next) {
            if ($msg->isa('Claude::Agent::Message::Result')) {
                $result = $msg->result // '';
                last;
            }
        }

        return {
            content => [{ type => 'text', text => $result }],
        };
    }
);

Sync handlers continue to work unchanged. The SDK automatically wraps synchronous return values in Futures, so you can mix sync and async tools freely.

Wrapping Up

The Claude Agent SDK for Perl brings agentic AI capabilities directly into your existing infrastructure. From custom MCP tools that access your application state, to a flexible hook system for security and observability, to specialised subagents for parallel expertise—the toolkit is designed for real-world automation. Whether you're building intelligent code review pipelines, DevOps automation, or AI-powered interfaces to legacy systems, the SDK provides the primitives you need while keeping you in control. The code is available on CPAN, and I look forward to seeing what you build with it.

https://metacpan.org/pod/Claude::Agent

Here are some extensions I've built already using the SDK:

https://metacpan.org/pod/Claude::Agent::Code::Review

https://metacpan.org/pod/Claude::Agent::Code::Refactor

https://metacpan.org/pod/Wordsmith::Claude

https://metacpan.org/dist/Acme-Claude-Shell/view/bin/acme_claude_shell

Horizon World - Maze Runner - Remixable - How to Guide

LNATION — Sun, 07 Sep 2025 11:10:37 +0000

Creating a remix

A prerequisite to remixing this world is that you have the Horizon Desktop Editor installed on your PC or Mac. If you do not have this installed please follow the instructions here - https://developers.meta.com/horizon-worlds/learn/documentation/get-started/install-desktop-editor

To install a version of Maze Runner - Remixable, navigate in your web browser to - https://horizon.meta.com/world/731602313376671

Click on the drop down next to the 'Go' button and then select the Remix in Editor option.

This will open the Desktop editor and create a version of the Maze Runner - Remixable world for you to edit.

If you then look under the script panel in the desktop editor you should find a README script. I recommend reading this first before proceeding further with this guide.

Changing the size of the maze

The default maze in this world is 9x9. You can change the size of the maze by navigating to the Maze object under the GameArea object in the Hierarchy panel.

In the properties panel you will see two properties width and height. You can change these values to any odd number. For example if you wanted a 15x15 maze you would set both the width and height to 15. Note that there are limits to how Large you can make the maze based on the assets used to create the maze. With the default assets you can make a maze up to 19x19. If you want to make a larger maze you will need to replace the wall assets and I will show you how to do this later in the guide.

After changing the width and height properties enter preview mode to see your new maze being generated.

Adding a third NPC

To add a third NPC to the game you will first need to add a new NPC gizmo to your world. You can do this via the Build -> Gizmos panel. Search for NPC and drag the gizmo into your scene. Position the NPC in the Lobby area.

Next rename your new NPC to something different to the defaults in the game world. In my example I will rename the NPC to Fern.

Customise the appearance of your NPC by clicking Edit Avatar in the properties panel. This will open a new window where you can customise many aspects of your NPC's appearance. When you are done be sure to click Save and then return to the desktop editor. Your avatar will now be updated in your scene.

Now create a new spawn point for the NPC. Go to the Build -> Gizmos panel and search for Spawn Point. Drag the spawn point gizmo into your scene and position it in the Lobby area in the same position and rotation as your NPC. Rename the spawn point to FernSpawnPoint (replacing Fern with the name of your Avatar).

Click back on your NPC and then in the properties panel attach either the RandomNPCRunner or DirectNPCRunner script to your NPC. The RandomNPCRunner script will make your NPC run randomly through the maze, while the DirectNPCRunner script will make your NPC run directly to the finish line. In my example I will use the RandomNPCRunner script. Set the relevant properties for the script, ensuring you link correctly the gameSpawnPoint and lobbySpawnPoint properties.

The final step to keep the Hierarchy panel tidy is to parent your new NPC objects and then add this new parent object to the Lobby object. To do this select the NPC and the trigger, right click and select create parent object. Rename this new parent object to the name of your NPC, in my example Fern.

Then drag this new parent object into the Lobby object in the Hierarchy panel.

Now return to preview mode, start a round and you will see your new NPC running through the maze.

Replacing the maze wall assets

To customize the maze walls, you can swap out the default wall assets for your own. This guide will show you how to create a new asset and attach it to the maze. To use a low-vertex cube as the wall, start by adding a standard Horizon cube shape. Open the Build -> Shapes panel, search for Cube, and drag it into your scene. Rename the cube to CustomMazeWall. The position of the cube does not matter as we will later delete this object.

What is important is to set the properties scale, our default wall assets are 4 wide and 10 high, this is configurable but for this guide we will keep these dimensions. Set the scale property to 4, 10, 4. Optionally set the Tint Color, Tint Stength and Brightness properties.

Next ensure the cube is animated by changing the Motion to Animated.

Now select the asset in the Hierarchy panel, right click and select create asset.

With the new asset created you can now delete the CustomMazeWall object from your scene.

Then select the Maze object in the Hierarchy panel, under the GameArea object.

In the properties panel under the attached script you now need to set the wallDetailed and wallSimple properties to your new asset. Then we need to fix the rotation of the wall asset, set the wallDefaultRotation to hz.Vec3(0,0,0), wallRotateOn to Y and wallDropOffset to 0.1.

Run your game and you will see the maze walls are now using your new asset. With this asset you can increase the width and height without the vertex count limit, however you will hit animation limits if you go too high. Below is an example of a 31x31 maze using this asset.

Horizon World Tutorial - Maze Runner - Part 5 - NPC runners

LNATION — Sat, 06 Sep 2025 13:15:51 +0000

In the previous parts of this tutorial series, we built the world, created core gameplay features, added background music, displayed a timer on the HUD, and implemented a random maze generator. In this final section, we'll introduce NPC runners to enhance the challenge. We'll create two types of NPCs: one that navigates the maze randomly, and another that heads straight for the finish line. To keep the game balanced, the direct runner will move slower than the random runner.

Let's get started! We will begin with the random runner. First, open the Maze Runner project you created in the previous parts of this tutorial series in the Desktop editor. We will first need to add an NPC character to the project. Today we will use NPC gizmo. Open the gizmo panel and search for "NPC". Drag and drop the NPC gizmo into the scene. Position the NPC in your lobby area. Adjust the rotation so they face in towards the center of the lobby area. Set the display name to anything you like, in my example I will use 'Rex', set the object name to be the same.

Next, we will quickly customise our NPC. Click the 'Edit Avatar' button in the properties panel. This will open the avatar editor in a web browser. Here you can change the appearance of your NPC. Edit the avatar to your liking, then save your changes and return to the desktop editor. Refresh and the NPC will update to reflect your changes.

(Note: the NPC editor in your web browser may be slightly broken, so some guess work might be required.)

Once you are happy with you NPC'S appearance, you will need to add a spawn location in the same position that you set your avatar. This will be used to spawn the NPC back into the correct position after a maze round has been completed. To do this, drag and drop a spawn point gizmo into the scene. Position it in the same location as your NPC and set the rotation to match. Rename the spawn point to RexSpawnPoint (replacing Rex with the name of your Avatar).

Now that the NPC and its spawn point are set up, it's time to start coding its behavior. In the Scripts panel, add a new script and name it RandomNPCRunner. After creating the script, attach it to your NPC object to begin controlling its movement.

Open the script in your editor and you should see the default boilerplate code.

import * as hz from 'horizon/core';

class RandomNPCRunner extends hz.Component<typeof RandomNPCRunner> {
  static propsDefinition = {};

  start() {

  }
}
hz.Component.register(RandomNPCRunner);

As usual we will import our GameState and Events types to help us manage the game state and setup listeners for events.

import { GameState, Events } from 'GameUtils';

This time, we'll also import the Npc and 'NpcPlayer' classes. This allows us to cast the NPC asset to the appropriate type so we have access to the functions required to control its behaviour programmatically.

import { Npc, NpcPlayer } from 'horizon/npc';

Next we will define our propsDefinition to include the customisable properties we will need to control the NPC's behavior. We will need a property to define the max and min speed the NPC can move at, as well as properties to define the teleport location into the maze and back to the lobby. Finally we will add an offset to ensure the NPCs do not all run in a straight line centered to the center of the maze path.

    static propsDefinition = {
        minSpeed: { type: hz.PropTypes.Number, default: 3 },
        maxSpeed: { type: hz.PropTypes.Number, default: 7 },
        gameSpawnPoint: { type: hz.PropTypes.Entity },
        lobbySpawnPoint: { type: hz.PropTypes.Entity },
        offset: { type: hz.PropTypes.Number, default: 0 }
    };

Now return to your desktop editor and you will see the script is failing to compile because it cannot find the horizon/npc module. To fix this, we need to add the NPC package to our project. Open the scripts panel, and click on the settings icon. Navigate to the API panel and then enable horizon/npc.

Click save and allow for the scripts to recompile. Once that is done you should see the script properties appear. Set the gameSpawnPoint and lobbySpawnPoint properties to the appropriate entities in your scene. Set the offset to 0.5.

With that set return to your code editor, before we extend this class we need to think about how we will get the Maze path coordinates accessible to our NPC script. We do not want our NPC to run directly into walls!. To do this we will implement a new Event in GameUtils.ts and then update our Maze.ts to broadcast the path coordinates once the maze has been generated. Open GameUtils.ts and add the following event to the Events object.

    mazeCarved: new hz.LocalEvent<{ maze: ( { x: number, y: number, z: number, type: string } | undefined)[][] }> ('mazeCarved'),

Notice how we are dropping the wall property from our default maze cell, this is just to reduce the amount of data we need to pass around through the event limiting the data to what is required by the NPC. The important information for the NPC is the actual path co-ordinates.

Next we need to update our Maze.ts script to broadcast this event once the maze has been generated. Open Maze.ts, inside the preStart function, inside the gameStateChanged callback, after you have carved the maze in the Starting state, add the following line of code.

                this.broadcastCarve();

Then at the end of the Maze class add a private function broadcastCarve to handle the actual broadcasting of the event.

    private broadcastCarve(): void {

    }

We will first need to first get a reference to our 2d array walls grid.

        let walls = this.walls;

Next we will create a new 2D array to hold the condensed maze data.

        let condensed: ({ x: number, y: number, z: number, type: string } | undefined)[][] = [];

Then we will loop through each row of the walls array, rebuilding the row to only include the x,y,z and type properties where type is not 'W'. If the cell is a wall we will push undefined to the new array.

        for (let row of walls) {
            let condensedRow: ({ x: number, y: number, z: number, type: string } | undefined)[] = [];
            for (let cell of row) {
                if (cell.type === 'W') {
                    condensedRow.push(undefined);
                } else {
                    condensedRow.push({ type: cell.type, x: cell.x, y: cell.y, z: cell.z });
                }
            }
            condensed.push(condensedRow);
        }

We then set the start and end cell types to 'S' and 'E' respectively. To make future logic easier in the NPC script. Note: if you do change the start or end cell locations you will need to update these lines accordingly.

        condensed[1][1]!.type = 'S'; // Set the start cell type
        condensed[condensed.length - 2][condensed[condensed.length - 2].length - 2]!.type = 'E'; // Set the end cell type

Finally we will broadcast the event with the condensed maze data.

        this.sendLocalBroadcastEvent(Events.mazeCarved, { maze: condensed });

Your final broadcastCarve function should look like this:

    private broadcastCarve(): void {
        let walls = this.walls;
        let condensed: ({ x: number, y: number, z: number, type: string } | undefined)[][] = [];
        for (let row of walls) {
            let condensedRow: ({ x: number, y: number, z: number, type: string } | undefined)[] = [];
            for (let cell of row) {
                if (cell.type === 'W') {
                    condensedRow.push(undefined);
                } else {
                    condensedRow.push({ type: cell.type, x: cell.x, y: cell.y, z: cell.z });
                }
            }
            condensed.push(condensedRow);
        }
        condensed[1][1]!.type = 'S'; // Set the start cell type
        condensed[condensed.length - 2][condensed[condensed.length - 2].length - 2]!.type = 'E'; // Set the end cell type
        this.sendLocalBroadcastEvent(Events.mazeCarved, { maze: condensed });
  }

We now have a global event being broadcast with the maze path coordinates once the maze has been generated. We can now return to our RandomNPCRunner.ts script and extend our class to implement the NPC logic. The first thing we will do is define some private properties to hold the casted AvatarAIAgent, the maze data, and a boolean if the game round is finished or not. Add the following below the propsDefinition:

    private npc: NpcPlayer | undefined;
    private maze: ({ x: number, y: number, z: number, type: string } | undefined)[][] = [];
    private finished: boolean = false;

So to setup our start function to cast our NPC to the correct type. We attached the script to the NPC object so we can use this.entity to get a reference to the entity the script is attached to. We will then cast this to an Npc object and then use the tryGetPlayer promise to retrieve a reference to the NpcPlayer object, which we can use to move the NPC. We need to wrap this in a setTimeout to overcome a race condition you will only encounter after publishing your world.

    start() {
        this.async.setTimeout(() => {
            this.entity.as(Npc).tryGetPlayer().then(player => this.npc = player);
        }, 3000);
    }

Within the same function we will setup the listener for the mazeCarved event we created earlier. When this event is received we will store the maze data in our private maze property. Add this before the setTimeout.

        this.connectLocalBroadcastEvent(
            Events.mazeCarved,
            (data: { maze: ({ x: number, y: number, z: number, type: string } | undefined)[][] }) => {
                this.maze = data.maze;
            }
        );

We need to setup a listener for the gameStateChanged event. This will allow us to respond to changes in the game state. We will add this listener within a preStart function, add the following code before the start function:

    preStart() {
        this.connectLocalBroadcastEvent(
            Events.gameStateChanged,
            (data: {
                fromState: GameState,
                toState: GameState,
            }) => this.handleGameStateChanged(data.fromState, data.toState),
        );
    }

Next to create the handleGameStateChanged function referenced in the listener. This function will implement a switch statement based on the new game state. We will handle four states: Starting, Playing, Ending, and Finished. On Starting we will set our finished property to false. On Playing we will call a function to move the NPC into the maze. On Ending we will set the finished property to true, and on Finished we will call a function to move the NPC back to the lobby and clear the maze data. Add the following function below the start function:

    private handleGameStateChanged(fromState: GameState, toState: GameState): void {
        switch (toState) {
            case GameState.Starting:
                this.finished = false;
                break;
            case GameState.Playing:
                this.moveNPCToMatch();
                break;
            case GameState.Ending:
                this.finished = true;
                break;
            case GameState.Finished:
                this.moveNPCToLobby();
                this.maze = [];
                break;
            default:
                break;
        }
    }

Now to implement the two functions referenced in the switch statement. First we will implement the moveNPCToMatch function. This function will teleport the NPC to the maze spawn point, and then call another function setNPCPath to start moving the NPC randomly through the maze at a random speed. Add the following function below the handleGameStateChanged function:

    private moveNPCToMatch(): void {
        let player = this.npc;
        if (player) {
            this.props.gameSpawnPoint?.as(hz.SpawnPointGizmo)?.teleportPlayer(player);
            this.async.setTimeout(() => {
                this.setNPCPath();
            }, 1000);
        }
    }

Note how we are using async.setTimeout to delay the call to setNPCPath by 1 second. This is to ensure the NPC has fully teleported before we start moving it. There may be a more elegant way to handle this that I am not aware of at this time, but the teleport function does not return a promise or have a callback to indicate when the teleport has completed (to my knowledge).

Next we will implement the setNPCPath function, we will step through this function in stages as it is the most complex part of the script. Start by adding the function definition below the moveNPCToMatch function:

     private setNPCPath(): void {
        if (!this.npc || !this.maze) return;


     }

Now we are going to abstract some logic into a helper function buildMazePath which we will use to build the path the NPC will take through the maze. Add the following callback inside the setNPCPath function:

        let path = this.buildMazePath();

Then to implement the buildMazePath function, add the following function definition below the setNPCPath function:

    private buildMazePath(): { position: hz.Vec3, direction: string }[] {

    }

To start we will define some local variables to hold the current position of the NPC in the maze grid, as well as the an array of Vec3 positions representing the path the NPC will take. We will also define an array to hold the possible directions the NPC can move in, a visited set which we will use to prevent the same paths from being taken twice and a last found index we can use to backtrack when we find dead ends.

        let maze = this.maze;
        let x: number = 1; 
        let y: number = 0.5;
        let z: number = 1;
        let path: { position: hz.Vec3, direction: string }[] = [];
        let dirs: [number, number, string][] = [
            [0, 1, 'up'],
            [1, 0, 'right'],
            [0, -1, 'down'],
            [-1, 0, 'left'],
        ];
        let visited = new Set<string>();
        let lastFoundIndex = 2;

Next we will add the starting position to the path array. We will use the x and z coordinates to get the world position from the maze grid, and add the y offset from our props to ensure the NPC is positioned correctly above the ground. We will also need to set the visited set to include the starting position.

        path.push({ position: new hz.Vec3(maze[z][x]!.x, y, maze[z][x]!.z), direction: 'start' });
        visited.add(`${x},${z}`);

After we will implement a while loop to continue building the path until we reach the end of the maze.

        while (path[path.length - 1].direction !== 'end') {

        }

Inside the loop we will first need to define a scoped variable found that will be used to track whether a valid direction was found. We will also shuffle the directions array to ensure the NPC moves in a random direction when given the opportunity.

            let found = false;
            dirs = dirs.sort(() => Math.random() - 0.5);

We will then loop through each direction in the shuffled directions array.

            for (const dir of dirs) {

            }

Inside the directions loop we will first calculate the next x and z coordinates based on the current position and the direction being checked.

                let nextX = x + dir[0];
                let nextZ = z + dir[1];

Then we will add a safety check to ensure the next coordinates are within the bounds of the maze grid and have not already been visited.

        if (
          nextX <= 0 || nextX >= this.maze.length ||
          nextZ <= 0 || nextZ >= this.maze[0].length ||
          visited.has(`${nextX},${nextZ}`)
        ) continue;

Now we will get a reference to the next cell in the maze grid.

        let cell = maze[nextX][nextZ];

If the cell is not 'undefined' then we know that it is a valid path cell, remember we filter out walls when we broadcast the maze data.

        if (cell) {

        }

Then push push the new position and direction into the path array, check if the cell type is 'E' if it is then set the direction to 'end' so that we exit the parent while loop on the next iteration.

            path.push({
                position: new hz.Vec3(cell.x, y, cell.z),
                direction: cell.type === 'E' ? 'end' : dir[2]
            });

After set visited to include the new position, update the current x and z coordinates to the new position, set found to true, reset lastFoundIndex, and break out of the directions loop as we have found a valid direction to move in.

            visited.add(`${nextX},${nextZ}`);
            x = nextX;
            z = nextZ;
            found = true;
            lastFoundIndex = 2; // Reset last found index
            break;

Finally within the while loop but outside the directions loop we will check if no valid direction was found, aka a dead end. If this is the case we will backtrack to the last found index in the path array, update the current x and z coordinates to the backtracked position, and increment the last found index so that if we can continue backtracking in the next loop until we find a valid new direction or run out of positions to backtrack to.

First add the conditional code:

        if (!found) {
            if (path.length > 1 && lastFoundIndex < path.length) {

            } else {
                break;
            }
        }

Here we first check if there are more than 1 position in the path array (we cannot backtrack from the start position) and that the lastFoundIndex is less than the length of the path array (to prevent out of bounds errors).

Next within the if conditional we will get the last position from the path array based on the lastFoundIndex.

                let lastStep = path[path.length - lastFoundIndex];
                let prev = lastStep.position;

We will then update the current x and z coordinates to this position. We need to find the x and z indexes in the maze grid that match the x and z coordinates of the last position. We can do this by using findIndex on the maze array.

                x = maze.findIndex(row => row.some(cell => cell && cell.x === prev.x && cell.z === prev.z));
                z = maze[x].findIndex(cell => cell && cell.x === prev.x && cell.z === prev.z);

Then we will push a new position into the path array with the opposite direction to indicate we are backtracking.

                path.push({ 
                    position: new hz.Vec3(prev.x, y, prev.z), 
                    direction: lastStep.direction == 'up' 
                        ? 'down' 
                        : lastStep.direction == 'down' 
                            ? 'up' 
                            : lastStep.direction == 'left' 
                                ? 'right' 
                                : 'left' 
                });

And finally we will increment the lastFoundIndex by 2 so that we can continue backtracking in the next loop if required. We increment by 2 because we want to skip the last position we just backtracked to, and get the one before that.

                lastFoundIndex += 2;

Finally outside the while loop we will return the built path array.

        return path;

Your final buildMazePath function should look like this:

    private buildMazePath(): { position: hz.Vec3, direction: string }[] {
        let maze = this.maze;
        let x: number = 1; 
        let y: number = 0.5;
        let z: number = 1;
        let path: { position: hz.Vec3, direction: string }[] = [];
        let dirs: [number, number, string][] = [
            [0, 1, 'up'],
            [1, 0, 'right'],
            [0, -1, 'down'],
            [-1, 0, 'left'],
        ];
        let visited = new Set<string>();
        let lastFoundIndex = 2;

        path.push({ position: new hz.Vec3(maze[x][z]!.x, y, maze[x][z]!.z), direction: 'start' });
        visited.add(`${x},${z}`);

        while (path[path.length - 1].direction !== 'end') {
            let found = false;
            dirs = dirs.sort(() => Math.random() - 0.5);

            for (const dir of dirs) {
                let nextX = x + dir[0];
                let nextZ = z + dir[1];

                if (
                    nextX <= 0 || nextX >= this.maze.length ||
                    nextZ <= 0 || nextZ >= this.maze[0].length ||
                    visited.has(`${nextX},${nextZ}`)
                ) continue;

                let cell = maze[nextX][nextZ];
                if (cell) {
                    path.push({
                        position: new hz.Vec3(cell.x, y, cell.z),
                        direction: cell.type === 'E' ? 'end' : dir[2]
                    });
                    visited.add(`${nextX},${nextZ}`);
                    x = nextX;
                    z = nextZ;
                    found = true;
                    lastFoundIndex = 2;
                    break;
                }
            }

            if (!found) {
                if (path.length > 1 && lastFoundIndex < path.length) {
                    let lastStep = path[path.length - lastFoundIndex];
                    let prev = lastStep.position;
                    x = maze.findIndex(row => row.some(cell => cell && cell.x === prev.x && cell.z === prev.z));
                    z = maze[x].findIndex(cell => cell && cell.x === prev.x && cell.z === prev.z);
                    path.push({
                        position: new hz.Vec3(prev.x, y, prev.z),
                        direction: lastStep.direction == 'up' 
                            ? 'down' 
                            : lastStep.direction == 'down'
                                ? 'up' 
                                : lastStep.direction == 'left'
                                ? 'right'
                                : 'left'
                    });
                    lastFoundIndex += 2;
                } else {
                    break;
                }
            }
        }

        return path;
    }

Now that we have the path built, we can return to the setNPCPath function. We have a path built but it is not yet optimised for smooth movement. We will need to simplify the path to remove unnecessary points and then smooth the path to create a more natural movement using a filter. Add the following code below the call to buildMazePath:

    path = path.filter((step, idx, arr) => {
      // Keep the last occurrence of each consecutive direction
      return (
        idx === arr.length - 1 ||
        step.direction !== arr[idx + 1].direction
      );
    });

This filter will remove consecutive steps in the same direction, keeping only the last occurrence. This helps to reduce jittery movement when the NPC is moving in a straight line.

Next we will create a new variable dir to hold the current direction the NPC is facing.

        let dir: hz.Vec3 = this.npc!.forward.get();

Then we will chain promises to rotate and move to each position in the path sequentially. We will start by rotating the NPC to face the initial direction, then for each position in the path we will rotate to face the new direction and then move to that position at a random speed between the min and max speed defined in our props. We will also check if the finished property is true before each action, if it is we will throw an error to break out of the promise chain.

First lets define the promise variable, we will start the chain by rotating the NPC to face the initial direction, this shouldn't actually change the rotation as the NPC should already be facing this direction, but it ensures the promise chain starts correctly.

        let promise = this.npc!.rotateTo(dir);

Then we will loop through each position in the path array.

        for (const pos of path) {

        }

Chain the promises to first rotate to face the new direction

            promise = promise
                .then(() => {
                    if (this.finished) throw new Error('Maze run has finished.');
                    if (pos.direction === 'start') return; // Skip the start position
                    if (pos.direction === 'up') dir = new hz.Vec3(-1, 0, 0);
                    else if (pos.direction === 'down') dir = new hz.Vec3(1, 0, 0);
                    else if (pos.direction === 'left') dir = new hz.Vec3(0, 0, -1);
                    else if (pos.direction === 'right') dir = new hz.Vec3(0, 0, 1);
                    else dir = this.npc!.forward.get(); // End
                    return this.npc!.rotateTo(dir);
                })

Then move to the new position at a random speed between the min and max speed defined in our props. We will also adjust the position by the offset defined in our props to ensure the NPC does not run directly in line with the center of the maze path.

                .then(() => {
                    if (this.finished) throw new Error('Maze run has finished.');
                    let randomSpeed = (Math.random() * (this.props.maxSpeed - this.props.minSpeed)) + this.props.minSpeed;
                    let options = {
                        movementSpeed: randomSpeed
                    };
                    pos.position.z += this.props.offset; // Adjust height based on offset
                    pos.position.x += this.props.offset;
                    return this.npc!.moveToPosition(pos.position, options);
                });

Your final setNPCPath function should look like this:

     private setNPCPath(): void {
        if (!this.npc || !this.maze) return;

        let path = this.buildMazePath();

        path = path.filter((step, idx, arr) => {
            // Keep the last occurrence of each consecutive direction
            return (
                idx === arr.length - 1 ||
                step.direction !== arr[idx + 1].direction
            );
        });

        let dir: hz.Vec3 = this.npc.forward.get();

        let promise = this.npc!.rotateTo(dir);

        for (const pos of path) {
            promise = promise
                .then(() => {
                    if (this.finished) throw new Error('Maze run has finished.');
                    if (pos.direction === 'start') return; // Skip the start position
                    if (pos.direction === 'up') dir = new hz.Vec3(-1, 0, 0);
                    else if (pos.direction === 'down') dir = new hz.Vec3(1, 0, 0);
                    else if (pos.direction === 'left') dir = new hz.Vec3(0, 0, -1);
                    else if (pos.direction === 'right') dir = new hz.Vec3(0, 0, 1);
                    else dir = this.npc!.forward.get(); // End
                    return this.npc!.rotateTo(dir);
                })
                .then(() => {
                    if (this.finished) throw new Error('Maze run has finished.');
                    let randomSpeed = (Math.random() * (this.props.maxSpeed - this.props.minSpeed)) + this.props.minSpeed;
                    let options = {
                        movementSpeed: randomSpeed
                    };
                    pos.position.z += this.props.offset; // Adjust height based on offset
                    pos.position.x += this.props.offset;
                    return this.npc!.moveToPosition(pos.position, options);
                });
        }
    }

The final function we need to implement is moveNPCToLobby. This function will teleport the NPC back to the lobby spawn point.

    private moveNPCToLobby(): void {
        let player = this.npc;
        if (player) {
            this.props.lobbySpawnPoint?.as(hz.SpawnPointGizmo)?.teleportPlayer(player);
            this.async.setTimeout(() => {
                let pos = this.props.lobbySpawnPoint?.position.get();
                let rot = this.props.lobbySpawnPoint?.forward.get();
                this.npc?.moveToPosition(pos!, { movementSpeed: 2 }).then(() => {
                    this.npc!.rotateTo(rot!);
                });
            }, 1000);
        }
    }

We first get a reference to the NPC's player object, then use the lobby spawn point to teleport the player back to the lobby. We then use async.setTimeout to delay for 1 second to ensure the teleport has completed before moving and rotating the NPC to face the correct direction in the lobby. We need this async delay especially if you reduce the countdown timer in the GameController script to less than 10 seconds, otherwise the NPC may still be moving in the maze when they are teleported so will continue moving in the lobby after being teleported. They will never be able to reach the intended position in the game thus this resolves the issue by resetting their position.

Now save all your modified script files, return to the desktop editor and allow the scripts to recompile. Once that is done, enter play mode and start a game round. You should see your NPC teleport into the maze and start running randomly through the maze at varying speeds. As the maze is currently small they should reach the end quite quickly. Once they reach the end they will stop moving until the round is finished, at which point they will teleport back to the lobby.

Now that we have the random NPC runner working, lets look at implementing the direct NPC runner. This NPC will always head straight for the finish line, but will move slower than the random runner to keep the game balanced. To implement this we can simply duplicate our RandomNPCRunner script and make a few modifications. In the scripts panel, right click on RandomNPCRunner and select duplicate. Rename the new script to DirectNPCRunner.

Next create a new NPC in your scene using the same steps as before, but this time set the display name and object name to something different to your first NPC. In my example I will use 'Eliza'. Create a new spawn point for this NPC in the same way as before, and rename it to ElizaSpawnPoint (replacing Eliza with the name of your Avatar). Next create the teleport point for this NPC and set its position to match the avatar's position. Finally attach the DirectNPCRunner script to this new NPC and set the script properties accordingly. For now leave the speed properties the same as the random NPC, we will adjust these in the script next.

If you were to now run your game you will have two NPCs running randomly through the maze. To modify this second NPC to run directly to the finish line we will need to make some changes to the DirectNPCRunner script. Open the DirectNPCRunner script in your editor. First we will need to rename our class, change all references to RandomNPCRunner to DirectNPCRunner, and then update the minSpeed and maxSpeed properties to be slower than the random NPC. In my example I will set the min speed to 2 and the max speed to 4. Update the propsDefinition as follows:

        minSpeed: { type: hz.PropTypes.Number, default: 2 },
        maxSpeed: { type: hz.PropTypes.Number, default: 4 },

To implement the new direct pathing logic we will only need to rewrite one function and that is the buildMazePath. We are going to take a different approach to building the path this time. The algoirithm we will be using is known as DFS or Depth First Search. This algorithm explores as far as possible along each branch before backtracking. This is a good fit for our maze as it will allow us to find the shortest path to the end of the maze. We will implement this using a stack data structure to keep track of the current path being explored. We will also use a visited set to keep track of the cells that have already been explored to prevent infinite loops. First we should define a new interface to represent each cell in the stack. Add the following code above the DirectNPCRunner class definition after the import statements:

interface MazeNode {
    x: number;
    z: number;
    prev?: MazeNode;
    direction?: string;
}

Then return to the buildMazePath function and replace the entire function with the following code:

    private buildMazePath(): { position: hz.Vec3, direction: string }[] {
        let maze = this.maze;
        let x: number = 1; 
        let y: number = 0.5;
        let z: number = 1;
        let path: { position: hz.Vec3, direction: string }[] = [];
        let dirs: [number, number, string][] = [
            [0, 1, 'up'],
            [1, 0, 'right'],
            [0, -1, 'down'],
            [-1, 0, 'left'],
        ];


     }

These are all the same variables we defined in the previous version of the function. Next we will define our stack and visited set. We will also define a variable to hold the end node once we find it.

        let queue: MazeNode[] = [{ x: x, z: z }];
        let visitedBFS = Array.from({ length: maze.length }, () => Array(maze[0].length).fill(false));
        visitedBFS[x][z] = true;
        let endNode: MazeNode | undefined;

To implement the DFS we will use a while loop to continue exploring the maze until we find the end node or run out of nodes to explore. We will use the queue variable as our stack iteratting until it is empty. We will use shift to get the last node added to the stack. We will then check if this node is the end node, if it is we will set the endNode variable and break out of the loop. If it is not the end node we will loop through each direction in the directions array and calculate the next x and z coordinates. We will then check if these coordinates are within the bounds of the maze grid and have not already been visited. If they are valid we will get a reference to the next cell in the maze grid and check if it is not a wall. If it is a valid path cell we will mark it as visited and push it onto the stack with a reference to the current node as its previous node. We will also set the direction property to indicate which direction we moved to reach this cell.

        while (queue.length > 0) {
            let current = queue.shift()!;
            let cell = maze[current.x][current.z];
            if (cell && cell.type === 'E') {
                endNode = current;
                break;
            }

            for (const [dx, dz, dir] of dirs) {
                let nx = current.x + dx;
                let nz = current.z + dz;
                if (
                    nx < 0 || nx >= maze.length ||
                    nz < 0 || nz >= maze[0].length ||
                    visitedBFS[nx][nz]
                ) continue;
                let nextCell = maze[nx][nz];
                if (nextCell && nextCell.type !== 'W') {
                    visitedBFS[nx][nz] = true;
                    queue.push({ x: nx, z: nz, prev: current, direction: nextCell.type === 'E' ? 'end' : dir });
                }
            }
        }

Once we have found the end node we will need to reconstruct the path from the end node back to the start node using the previous node references. We will loop through the nodes starting from the end node and push each position and direction into the path array. We will then reverse the path array to get it in the correct order from start to end.

        // Reconstruct path from endNode
        if (endNode) {
            let node: MazeNode | undefined = endNode;
            while (node) {
                let cell = maze[node.x][node.z];
                let direction = node.direction ?? (path.length === 0 ? 'end' : 'start');
                path.push({ position: new hz.Vec3(cell!.x, y, cell!.z), direction });
                node = node.prev;
            }
            path.reverse();
        }

Finally we will return the built path array.

        return path;

Your final implementation of the buildMazePath function using DFS should look like this:

    private buildMazePath(): { position: hz.Vec3, direction: string }[] {
        let maze = this.maze;
        let x: number = 1; 
        let y: number = 0.5;
        let z: number = 1;
        let path: { position: hz.Vec3, direction: string }[] = [];
        let dirs: [number, number, string][] = [
            [0, 1, 'up'],
            [1, 0, 'right'],
            [0, -1, 'down'],
            [-1, 0, 'left'],
        ];
        let queue: MazeNode[] = [{ x: x, z: z }];
        let visitedBFS = Array.from({ length: maze.length }, () => Array(maze[0].length).fill(false));
        visitedBFS[x][z] = true;
        let endNode: MazeNode | undefined;

        while (queue.length > 0) {
            let current = queue.shift()!;
            let cell = maze[current.x][current.z];
            if (cell && cell.type === 'E') {
                endNode = current;
                break;
            }

            for (const [dx, dz, dir] of dirs) {
                let nx = current.x + dx;
                let nz = current.z + dz;
                if (
                    nx < 0 || nx >= maze.length ||
                    nz < 0 || nz >= maze[0].length ||
                    visitedBFS[nx][nz]
                ) continue;
                let nextCell = maze[nx][nz];
                if (nextCell && nextCell.type !== 'W') {
                    visitedBFS[nx][nz] = true;
                    queue.push({ x: nx, z: nz, prev: current, direction: nextCell.type === 'E' ? 'end' : dir });
                }
            }
        }

        // Reconstruct path from endNode
        if (endNode) {
            let node: MazeNode | undefined = endNode;
            while (node) {
                let cell = maze[node.x][node.z];
                let direction = node.direction ?? (path.length === 0 ? 'end' : 'start');
                path.push({ position: new hz.Vec3(cell!.x, y, cell!.z), direction });
                node = node.prev;
            }
            path.reverse();
        }

        return path;
    }

Now save the script file, return to the desktop editor and allow the scripts to recompile. Once that is done, enter play mode and start a game round. You should see your direct NPC teleport into the maze and start running directly to the end of the maze at a slower speed than the random NPC. Once they reach the end they will stop moving until the round is finished, at which point they will teleport back to the lobby.

With both random and direct NPC runners now implemented, your maze game features two distinct challenges for players to compete against.

This concludes the this tutorial series I hope you have enjoyed it and do not stop here, there are plenty of opportunities to expand and refine your maze game further. I’m excited to see how you build on these foundations!

Horizon World Tutorial - Maze Runner - Part 4 - Randomly generated mazes

LNATION — Tue, 02 Sep 2025 21:56:11 +0000

In the earlier parts of this tutorial series, we established the foundational world, built out the main gameplay features, and introduced a custom UI timer and background music. Now, our focus shifts to generating the maze itself. While there are many maze generation algorithms to choose from, we'll be using a straightforward depth-first search (DFS) carve algorithm for this guide. This method works by recursively carving out random paths in a grid to create the maze structure. One important note: the carve implementation I will use today require both the width and height of the grid to be odd numbers to ensure the maze renders properly.

To begin, create a new script dedicated to maze generation. Open your world in the desktop editor and use the UI to add a new script.

After creating the script, open it. You should see the familiar boilerplate code as a starting point.

import * as hz from 'horizon/core';

class Maze extends hz.Component<typeof Maze> {
  static propsDefinition = {};

  start() {

  }
}
hz.Component.register(Maze);

Like with the other files we must first import the Events and GameState from our GameUtils script. Add the import line before the class definition.

import { Events, GameState } from 'GameUtils';

Next we will plan our propsDefinition for the Maze component. This will include any properties we want to expose for customisation. We will make our maze size configurable and made up of two main properties: width and height, both of which will be integers representing the dimensions of the maze grid. For the maze walls we will use assets we will have two type of walls a simple wall and a detailed wall, we will need to set the default rotation of our walls and which column to rotate the detailed wall, the walls we will be using today will be 4x10x4. Also because we will make our maze dynamic we will need to position the start and end zones within the maze, so we will need properties to store a reference to them also. Extend the propsDefinition object in your class to the following:

    static propsDefinition = {
        wallDetailed: { type: hz.PropTypes.Asset, required: true },
        wallSimple: { type: hz.PropTypes.Asset, required: true },
        wallDefaultRotation: { type: hz.PropTypes.Vec3, default: new hz.Vec3(270, 0, 0) },
        wallRotateOn: { type: hz.PropTypes.String, default: 'Z' },
        wallWidth: { type: hz.PropTypes.Number, default: 4 },
        wallHeight: { type: hz.PropTypes.Number, default: 10 },
        wallDropOffset: { type: hz.PropTypes.Number, default: 0 },
        width: { type: hz.PropTypes.Number, default: 19 },
        height: { type: hz.PropTypes.Number, default: 19 },
        startPosition: { type: hz.PropTypes.Entity, required: true },
        startPositionY: { type: hz.PropTypes.Number, default: 1 },
        finishPosition: { type: hz.PropTypes.Entity, required: true },
    };

With that in place, save the file and return to the desktop editor. Create a new object, name this Maze, and attach the Maze script to it. This will then allow you to attach the necessary assets and configure the maze properties directly from the editor. For the maze walls in this tutorial we will use two assets that I have made public, search in the Assets panel for Maze Runner and then add the first wall asset to your world. After that, rename the object to WallDetailed and set the Motion to animated.

Once you have done that you next need to save the asset to your library, right click on the asset and select 'create asset', save it into your local asset directory. After that, repeat the process for the second wall asset, renaming it to WallSimple and remembering to set the Motion to animated as well.

Then with both assets saved you can delete the original wall objects from your scene, leaving only the newly created assets in your library. Navigate to the Maze object and when you click on WallDetailed you will be able to search for the relevant asset. Leave the wallWidth as 4, but set the maze width and height properties with the value of 9 and attach the GameSpawnPoint to the startPosition and Finish to finishPosition.

Now with the relevant properties set we in the desktop editor you can return to your code editor, and open Maze.ts. Next we will add a private property which we will use to store our maze grid. Beneath the propsDefinition add a line to define a private attribute that is an array of arrays of hashes. In typescript you need to explicitly define the hash that will be stored for type checking, in our hash we will have keys for the wall asset, grid type and x, y, and z positions.

    private walls: { wall: hz.Entity | undefined, type: string, x: number, y: number, z: number }[][] = [];

The next step is to generate the maze grid, this will involve creating a 2D array that represents the maze layout. Each cell in the grid will be an object that contains information about the wall asset to use, its position, and the type of wall which we will default to 'W' for wall when generating the grid. We will hook into the start function to populate this grid, we will do this via a callback function generateMazeGrid. Update the start function in Maze.ts to the following:

    start() {
        if (!this.walls.length) {
            this.generateMazeGrid();
        }
    }

Then to implement the generateMazeGrid function, we will first need to calculate the dimensions of the maze based on the wall width and the number of walls. This will give us the overall width and height of the maze.

    private generateMazeGrid() {
        let width = this.props.width * this.props.wallWidth;
        let height = this.props.height * this.props.wallWidth;

    }

Next we will need to calculate the start x, y and z positions for our grid, the y will always be half our wall height for our assets. The x will be half the full width of the maze minus half the asset width and the z will be zero minus half the full height of the maze minus half the asset width. This will ensure we start drawing the grid from the south east corner and end on the north west as our game is designed.

        let x = (width / 2) - (this.props.wallWidth / 2);
        let y = this.props.wallHeight / 2;
        let z = 0 - ((height / 2) - (this.props.wallWidth / 2));

Now we are going to iterate over the height and width of the maze to create the wall entities. We will need to recurse either the X or Z so we must store the start position for atleast one, in this example we will keep track of x, so next declare a startX variable.

        let startX = x;

To add variety to our maze, we'll randomly rotate the detailed wall assets so that different sides are visible each time the maze is generated. Since the simple wall looks the same on all sides, we can use a fixed rotation for it. Let's introduce a simpleRotation variable for the simple wall, while the detailed wall will use a random rotation. We can use the property we defined previously.

        let simpleRotation = hz.Quaternion.fromEuler(this.props.wallDefaultRotation);

We also need to create a local 2d array to hold our wall entities before we set the global property. Use the same type definition as the walls property.

        let walls: { wall: hz.Entity | undefined, type: string, x: number, y: number, z: number }[][] = [];

Next we need to do something a little strange, we need to declare a variable that is casted to either 'Entity' or 'undefined' and then set this to undefined. We will use this as a placeholder while our assets are loaded into entities.

        let undefined_entity: hz.Entity | undefined = undefined;

The final variable we need to declare is something I call at_the_races, this variable will by used to keep track of the number of wall entities that are still being spawned. There is more than one way to handle this race condition, but a simple approach is to use a counter that increments when a wall entity is spawned and decrements when it is finished.

        let at_the_races = 0;

Now to implement the iteration needed to generate our grid, we will iterate over the height and width of the maze to create the wall entities. Add the following after the at_the_races declaration:

        for (let i = 0; i < height; i += this.props.wallWidth) {
            let row = [];
            for (let j = 0; j < width; j += this.props.wallWidth) {

            }

        }

Then we need to first calculate the start x, y and z position for our grid wall. This must be a Vec3 and at this point should just be the x, y and z variables we have already defined, we will increment these later in our loops.

                let position = new hz.Vec3(
                    x,
                    y,
                    z
                );

Next, create a grid cell using the same type definition as the walls property. Initialize each property with the values you have at this stage, setting the type to W by default since all cells start as walls.

                let cell: { wall: hz.Entity | undefined, type: string, x: number, y: number, z: number } = { wall: undefined_entity, type: 'W', x: x, y: y, z: z };
                row.push(cell);

Now we need to decide which wall asset to spawn. For now we will implement simple logic that will make the third wall in each row a detailed wall. When we identify that we will spawn a detailed wall, we will also randomly rotate it via a helper function we will define later. Add the following after 'row.push(cell)'.

                let [asset, rotation] = (j + i / this.props.wallWidth) % 3 === 0
                    ? [this.props.wallDetailed, hz.Quaternion.fromEuler(this.randomWallRotation())]
                    : [this.props.wallSimple, simpleRotation];

Then increment at_the_races as a wall entity is about to be spawned via a promise.

                at_the_races++;

To spawn the asset we must first check if the asset variable is defined, then we can use hz.Entity.spawn(asset, position, rotation) to create the wall entity. When the promise resolves, we can set the cell walls entity property and decrement the at_the_races variable.

                if (asset) this.world.spawnAsset(asset, position, rotation).then(spawnedObjects => {
                    spawnedObjects.forEach(obj => {
                        cell.wall = obj;
                        at_the_races--;
                    });
                });

The final piece of code needed in the width iteration is to increment the x variable so that the next loop draws the next grid cell.

                x -= this.props.wallWidth;

Now that is our grid width row is being drawn correctly, next is the height iteration. After you exit the width iteration, you will need to push the row into the walls array, reset the x variable and increment the z variable so that the next loop draws the next grid row.

            walls.push( row );
            x = startX;
            z += this.props.wallWidth;

With that in place we have only our race condition to handle, after the height iteration add the following:

        let racer = 0;
        racer = this.async.setInterval(() => {
            if (at_the_races === 0) {
                this.walls = walls;
                this.sendLocalBroadcastEvent(Events.setGameState, { state: GameState.Ready, winner: undefined });
                this.async.clearInterval(racer);
            }
        }, 100);

This code sets up a setInterval that checks if all wall entities have been spawned. Once all walls are in place, it sets the walls property with the final grid, updates the game state to "Ready" via a setGameState event, and clears the interval to stop the checks.

Your current generateMazeGrid function should look like this:

    private generateMazeGrid() {
        let width = this.props.width * this.props.wallWidth;
        let height = this.props.height * this.props.wallWidth;
        let x = (width / 2) - (this.props.wallWidth / 2);
        let y = this.props.wallHeight / 2;
        let z = 0 - ((height / 2) - (this.props.wallWidth / 2));
        let startX = x;
        let simpleRotation = hz.Quaternion.fromEuler(this.props.wallDefaultRotation);
        let walls: { wall: hz.Entity | undefined, type: string, x: number, y: number, z: number }[][] = [];
        let undefined_entity: hz.Entity | undefined = undefined;
        let at_the_races = 0;

        for (let i = 0; i < height; i += this.props.wallWidth) {
            let row = [];
            for (let j = 0; j < width; j += this.props.wallWidth) {
                let position = new hz.Vec3(
                    x,
                    y,
                    z
                );
                let cell: { wall: hz.Entity | undefined, type: string, x: number, y: number, z: number } = { wall: undefined_entity, type: 'W', x: x, y: y, z: z };
                row.push(cell);
                at_the_races++;
                let [asset, rotation] = (j + i / this.props.wallWidth) % 3 === 0
                    ? [this.props.wallDetailed, hz.Quaternion.fromEuler(this.randomWallRotation())]
                    : [this.props.wallSimple, simpleRotation];
                if (asset) this.world.spawnAsset(asset, position, rotation).then(spawnedObjects => {
                    spawnedObjects.forEach(obj => {
                        cell.wall = obj;
                        at_the_races--;
                    });
                });

                x -= this.props.wallWidth;
            }
            walls.push( row );
            x = startX;
            z += this.props.wallWidth;
        }

        let racer = 0;
        racer = this.async.setInterval(() => {
            if (at_the_races === 0) {
                this.walls = walls;
                this.sendLocalBroadcastEvent(Events.setGameState, { state: GameState.Ready, winner: undefined });
                this.async.clearInterval(racer);
            }
        }, 100);
    }

Now before your code will compile we will need to implement the randomWallRotation function. Add the following code to your Maze class:

    private randomWallRotation(): hz.Vec3 {
        let rotation = 90 * Math.floor(Math.random() * 4);
        let on = this.props.wallRotateOn.toUpperCase();
        return on === 'X' 
            ? new hz.Vec3(this.props.wallDefaultRotation.x, this.props.wallDefaultRotation.y, rotation) 
            : on === 'Y' 
                ? new hz.Vec3(this.props.wallDefaultRotation.x, rotation, this.props.wallDefaultRotation.z) 
                : new hz.Vec3(this.props.wallDefaultRotation.x, this.props.wallDefaultRotation.y, rotation);
  }

This code calculates a random rotation and then uses a ternary operator to check whether the wallRotateOn property is set to either the X, Y or Z axis and returns a relevant vec3.

You will now be able to save, and enter preview mode in your desktop editor. You should see a 9x9 grid of walls in the center of the game area.

Next we need to setup our event listener so that we can randomly generate the maze via a carve function when the game state changes to Starting, we will also want to reset all grid cells to their initial state when the game state changes to Finished. We will implement this listener inside of a preStart function. Add the following code before the start function.

    preStart() {
        if (this.props.width % 2 === 0) throw new Error("Width must be odd");
        if (this.props.height % 2 === 0) throw new Error("Height must be odd");
        this.connectLocalBroadcastEvent(Events.gameStateChanged, (data) => {
            if (data.toState == GameState.Starting) {
                this.carve(1, 1);
            } else if (data.toState == GameState.Finished) {
                this.resetWalls();
            }
        });
    }

Note how we have added some validation to ensure the maze dimensions are odd numbers, this is to handle the earlier mentioned caveat with the algorithm we are about to implement which relies on a grid structure that is always odd in both dimensions to render perfectly.

To implement the carve function start with this boilerplate code:

    private carve(x: number, z: number, visited?: Set<string>): void {

    }

We have defined x and z as the coordinates of the current cell being processed in the maze. The carve function will use these coordinates to manipulate the maze data structure and create paths. The visited parameter is a Set that keeps track of all the cells that have been processed so far to avoid infinite loops. (even though this algorithm would never go into an infinite loop this is necessary for typescript).

Now we need to define some variables, first height and width which we can get from our properties and then a reference to walls.

        let height = this.props.height;
        let width = this.props.width;
        let maze = this.walls;

After a variable to define the drop on the y axis for the path.

        let drop = this.props.wallHeight - this.props.wallDropOffset;

Then the visited variable if it is not defined.

        if (!visited) visited = new Set<string>();

Next we need to check whether we have visited this cell, and if so return early. (Not really necessary, but good for clarity).

        const key = `${x},${z}`;
        if (visited.has(key)) return;
        visited.add(key);

Now we need to explore the neighboring cells. We will use a randomized depth-first search (DFS) approach to carve out the maze. First, we need to define the possible directions we can move in the maze.

        let dirs = [[0, -1], [1, 0], [0, 1], [-1, 0]];

Then we need to randomize the order of the directions to ensure that the maze is carved in a random pattern.

        dirs.sort(() => Math.random() - 0.5);

After we mark the current cell as part of the path and ensure we move the wall asset to be the floor.

        if (maze[z] && maze[z][x]) {
            if (maze[z][x].type === 'W') {
                maze[z][x].type = 'P';
                maze[z][x].wall?.position.set(new hz.Vec3(maze[z][x].x, maze[z][x].y - drop, maze[z][x].z));
            }
        }

Then we are ready to explore the neighbouring cells. We will use the randomised directions we created earlier to move to each neighbouring cell. Checking first whether we have hit an outer wall. If we have, we need to stop the carving process in that direction. We continue this process recursively until we have carved out the entire maze. Extend with the following code:

        for (let i = 0; i < 4; ++i) {
            let dx = dirs[i][0], dz = dirs[i][1];
            let nx = x + 2*dx, nz = z + 2*dz;
            if (nx > 0 && nx < width-1 && nz > 0 && nz < height-1) {
                if (maze[nz] && maze[nz][nx] && maze[nz][nx].type === 'W') {
                    maze[z+dz][x+dx].type = 'P';
                    maze[z+dz][x+dx].wall?.position.set(new hz.Vec3(maze[z+dz][x+dx].x, maze[z+dz][x+dx].y - drop, maze[z+dz][x+dx].z));
                    this.carve(nx, nz, visited);
                }
            }
        }

Your final implementation of the carve function should look like this:

    private carve(x: number, z: number, visited?: Set<string>): void {
        let height = this.props.height;
        let width = this.props.width;
        let maze = this.walls;
        let drop = this.props.wallHeight - this.props.wallDropOffset;
        if (!visited) visited = new Set<string>();
        const key = `${x},${z}`;
        if (visited.has(key)) return;
        visited.add(key);

        let dirs = [[0, -1], [1, 0], [0, 1], [-1, 0]];
        dirs.sort(() => Math.random() - 0.5);

        if (maze[z] && maze[z][x]) {
            if (maze[z][x].type === 'W') {
                maze[z][x].type = 'P';
                maze[z][x].wall?.position.set(new hz.Vec3(maze[z][x].x, maze[z][x].y - drop, maze[z][x].z));
            }
        }

        for (let i = 0; i < 4; ++i) {
            let dx = dirs[i][0], dz = dirs[i][1];
            let nx = x + 2*dx, nz = z + 2*dz;
            if (nx > 0 && nx < width-1 && nz > 0 && nz < height-1) {
                if (maze[nz] && maze[nz][nx] && maze[nz][nx].type === 'W') {
                    maze[z+dz][x+dx].type = 'P';
                    maze[z+dz][x+dx].wall?.position.set(new hz.Vec3(maze[z+dz][x+dx].x, maze[z+dz][x+dx].y - drop, maze[z+dz][x+dx].z));
                    this.carve(nx, nz, visited);
                }
            }
        }
    }

Finally for our script to run we need to quickly add a resetWalls function, this function will just iterate the walls variable and set all grid cells to W resetting their positions.

    private resetWalls(): void {
        for (let row of this.walls) {
            for (let cell of row) {
                if (cell.type === 'P') {
                    cell.wall?.position.set(new hz.Vec3(cell.x, cell.y, cell.z));
                    cell.type = 'W'; // Reset type to wall
                }
            }
        }
    }

Now if you return to your desktop editor and run preview mode, after you have waited for the maze to fully load you should be able to press the button and see the path drawn in the maze. You will however not spawn into the maze as we will implement that part next.

To ensure the players spawn into the maze correctly and the finish line is accessible, we need to position our entities based upon the grid that has been generated. Inside the Maze class update the racer interval function to set the start and finish positions based upon the grid cells:

        racer = this.async.setInterval(() => {
            if (at_the_races === 0) {
                this.walls = walls;
                this.props.startPosition?.position.set(new hz.Vec3(this.walls[1][1].x, this.props.startPositionY, this.walls[1][1].z));
                this.props.finishPosition?.position.set(new hz.Vec3(this.walls[this.walls.length - 2][this.walls[0].length - 2].x, this.props.wallHeight / 2, this.walls[this.walls.length - 2][this.walls[0].length - 2].z));
                this.sendLocalBroadcastEvent(Events.setGameState, { state: GameState.Ready, winner: undefined });
                this.async.clearInterval(racer);
            }
        }, 100);

Now before you try out this code, lets quickly fix the Loading phase of our game engine, if you remember we temporarily added some code in our GameController to automatically move into the Ready state but now we have the maze rendering and the event written we can remove this code. Open GameController.ts and remove the following line from the start function:

        this.setGameState(GameState.Ready, undefined);

Save your files, return to your desktop editor and allow for the scripts to compile. When you now enter preview mode, you will see the text will display 'Loading the Maze...' while you wait for the maze grid to be generated. Once generated you can press the button and you will be teleported into the maze, once you reach the finish line you will be declared the winner. We have a working Maze running game.

Before we finish for this instalment, lets now tidy up our game world. We no longer need the outer walls or floor for the game area so these objects can be removed. You may also want to move the finish object so it is not in view from the lobby while the maze is rendering.

In the end your game world should now look something like this:

This concludes this part of the tutorial. You now have a fully functional maze game with a randomly generated maze each time you play. In the final instalment of this series, we'll look at adding NPCs to race against within your maze.

Horizon World Tutorial - Maze Runner - Part 3 - HUD timer and background sound

LNATION — Mon, 01 Sep 2025 19:55:18 +0000

In our last tutorial, we setup the basic game mechanics for our Maze runner game. In this part, we will enhance the game by adding a custom UI timer to our HUD and some background sound to the world to improve the overall player experience.

Let's start by adding a custom UI timer to the players screen, to implement this we can extend the already existing localPlayerHUD script. Open this script in your editor to refamiliarise yourself with its structure. Notice that we currently import Events, but to properly display the timer during specific game states, we also need to import GameState. Update the import statement accordingly.

import { GameState, Events } from 'GameUtils';

Next we need to add some properties to store the timer state and ongoing duration. Below the existing properties, add the following code:

    private timer = new Binding<string>('0'); // Timer value in seconds
    private timerDisplay = new Binding<string>('flex'); // property to manage visibility of HUD
    private timerID: number = 0;

We have defined three properties, the timer which is a Binding<string> to hold the timer value, the timerDisplay which is a Binding<string> to manage the visibility of the HUD, and the timerID which is a number to keep track of the timer's interval ID. Note that we are using Binding to ensure that any changes to these properties will automatically update the UI.

With these properties in place, we next need to update our initializeUI to render the timer in the HUD. Locate the initializeUI function and replace it with the following:

    initializeUI() {
        return ui.View({
            children: [
                ui.View({
                    style: {
                        position: 'absolute',
                        display: this.timerDisplay,
                        bottom: 20,
                        left: 20,
                        backgroundColor: 'rgba(0, 0, 0, 0.5)',
                        borderRadius: 10,
                        padding: 10,
                    },
                    children: [
                        ui.Text({
                            text: this.timer,
                            style: {
                                fontSize: 24,
                                color: 'white',
                                textAlign: 'center',
                            }
                        })
                    ]
                }),
                ui.View({
                    style: {
                        position: 'absolute',
                        right: 20,
                        bottom: 20,
                        height: '50%',
                        width: 20,
                        backgroundColor: 'gray',
                        borderRadius: 10,
                    },
                    children: [
                        ui.View({
                            style: {
                                position: 'absolute',
                                bottom: 0,
                                width: '100%',
                                height: this.sprintProgress,
                                backgroundColor: 'blue',
                                borderRadius: 10,
                            },
                        }),
                    ]
                }),
            ],
            style: {
                position: 'relative',
                width: '100%',
                height: '100%',
            },
        });
    }

What we have done here is add a new UI.View component that will be displayed at the bottom left of the screen. This view contains a UI.Text component that binds to our timer property, allowing it to dynamically update as the timer changes. We use the timerDisplay property to control the visibility of the timer HUD. The view is styled with a semi-transparent background and rounded corners to ensure it is visually appealing and does not obstruct gameplay.

Now before we can test the timer, we need to do a little extra work to ensure the gameStateChanged event can reach our HUD, the problem is you cannot simply connect to a connectLocalBroadcastEvent as this listener gets destroyed when you change the ownership of the HUD. For this to work we need to send a sendNetworkEvent for each player HUD and listen to them via connectNetworkEvent. So next you need to open PlayerController and inside the handleGameStateChanged function you need to extend with the following code at the end.

    this.players.forEach((p: hz.Player) => {
        this.sendNetworkEvent(
            p,
            Events.gameStateChanged,
            { fromState, toState }
        );
    });

This code will ensure that all players receive the gameStateChanged event to their local HUD script when the game state changes. Next we need to setup a listener for our gameStateChanged Event, within this event we will show the timer HUD when we enter Starting state. The timer will being counting when we enter Playing state and will stop when we enter Ending state. We will connect to the event inside of our start function. After the existing setHUDSprint event listener add the following code:

    this.connectNetworkEvent(
        this.entity.owner.get(),
        Events.gameStateChanged,
        (data: {
            fromState: GameState,
            toState: GameState,
        }) => this.handleGameStateChanged(data.fromState, data.toState),
    );

Then to implement the handleGameStateChanged function after the start function add:

    handleGameStateChanged(fromState: GameState, toState: GameState) {
        if (toState === GameState.Starting) {
            this.showTimer();
        } else if (toState === GameState.Playing) {
            this.startTimer();
        } else if (toState === GameState.Ending) {
            this.stopTimer();
        }
    }

This function checks the new game state and calls the appropriate method to manage the timer's visibility and functionality. When the game state changes to Starting, it calls showTimer to make the timer visible. When it changes to Playing, it starts the timer with startTimer. Finally, when the game state changes to Ending, it stops the timer with stopTimer.

We need to next implement the showTimer, startTimer, and stopTimer functions in our HUD script. We will start with showTimer which will make the timer HUD visible. It will need to set the timerDisplay property to flex and reset the timer property to 0.

    private showTimer() {
        this.timerDisplay.set('flex');
        this.timer.set('0');
    }

Next we will add the startTimer function which will begin the timer's countdown. We will use async setInterval to ensure we do not block the main thread, we will use the timerID property to keep track of the interval.

    private startTimer() {
        let t = 0;
        this.timerID = this.async.setInterval(() => {
            t++;
            this.timer.set(t.toString());
        }, 1000);
    }

Finally, we will implement the stopTimer function which will stop the timer's countdown. This function will clear the interval using the timerID property and set the timerDisplay property to none.

    private stopTimer() {
        this.async.clearInterval(this.timerID);
        this.timerDisplay.set('none');
    }

With this in place when you now enter preview mode, you should see the timer HUD appear when the game state changes to Starting (when you press the button), start counting up when it changes to Playing (when you teleport into the game area), and stop counting and hide when it changes to Ending (when you reach the finish line).

Now that we have the timer working, let's add some sound to our game. Today we will be adding background music to enhance the gaming experience. We will use two sound tracks: one for the lobby and one for the game area.

First we will need to prepare our GameController, open this file in you code editor and then inside of the propsDefinition add definitions for our two sound assets:

    static propsDefinition = {
        countdownTimeInSeconds: { type: hz.PropTypes.Number, default: 10 },
        lobbySound: {type: hz.PropTypes.Entity},
        playingSound: {type: hz.PropTypes.Entity},
    };

Now that we have the properties defined, return to the desktop editor, navigate to the Sounds tab under Build, and change the dropdown to Music. Then you can choose two tracks to add into your world, for my example I will use Arcade Theme for the lobby and Flexin for the game area. Adjust the volume to your liking and disable the Play on Start option. Once you are happy, click on the GameController object and link your sound assets to the lobbySound and playingSound properties.

With the sound assets linked, return to your code editor and open GameController.ts. Next we will add some more private properties to store the casted AudioGizmo instances:

    private lobbySound: hz.AudioGizmo | undefined;
    private playingSound: hz.AudioGizmo | undefined;

Then we need to instantiate these properties, we will do this early inside of the start function, we can also begin playing the lobbySound at this point. As the beginning of the start function add the following:

        this.lobbySound = this.props.lobbySound?.as(hz.AudioGizmo);
        this.lobbySound?.play();
        this.playingSound = this.props.playingSound?.as(hz.AudioGizmo);

This code casts the linked sound entities to AudioGizmo instances and starts playing the lobby sound. Next, we will need to implement the logic to switch between the lobby and playing sounds based on the game state. Inside setGameState case GameState.Starting before the call to handleNewMatchStarting add:

                this.lobbySound?.stop();
                this.playingSound?.play();

Then inside the same setGameState function, add the case for GameState.Finished:

                this.playingSound?.stop();
                this.lobbySound?.play();

Now return to your desktop editor and run the preview mode, on start you should hear the lobby music, when you start playing the game the music should switch to the playing music, and when you finish the game it should switch back to the lobby music.

This concludes this part of the tutorial. In the next installment, we’ll tackle the actual generation of the maze.

DEV Community: LNATION

Introducing Object::Proto — A Prototype Object System for Perl

The Basics

What You Get

Built-in Types (Zero Overhead)

Slot Modifiers

Inheritance

Roles

Method Modifiers

Prototype Chains

Mutability Controls

Cloning & Introspection

Singletons

Function-Style Accessors

Performance

Extending the Type System from XS

For Moo/Moose Users: Object::Proto::Sugar

Sugar with Function-Style Accessors

Sugar Benchmarks vs Moo and Mouse

A Note on Compatibility

Loo: Yet Another Way To Introspect Data

Why Another Dumper?

Getting Started

Data::Dumper Compatibility

Colour Customisation

The Deparser

Reusable C Headers

Auto-Detection Done Right

Installation

Closing Thoughts

Learning XS - Sharing Reusable C Headers Between Perl XS Distributions

Introduction

The Example

Part 1: The Provider Distribution (Abacus)

Write the pure-C header

Write the Perl-facing XS header

Write the XS file

Write the Perl module with include_dir()

Write the Makefile.PL that installs headers

Write a test

Build and install Abacus

Part 2: The Consumer Distribution (Tally)

Write the Makefile.PL that finds Abacus headers

Write the XS file

Write the Perl module

Write a test

Build Tally (development mode)

Horus, Apophis, and Sekhmet: An C/XS Identifier Stack for Perl

Horus: Every UUID Version, One Module

Why multiple versions matter

Ten output formats

Bulk generation

Utilities

Sekhmet: ULIDs for When You Need Sortable and Compact

Monotonic mode

Time extraction

UUID interoperability

When to use Sekhmet vs Horus

Apophis: Content-Addressable Storage

How storage works

Identification without storage

Metadata

Namespace isolation

Verification

How They Fit Together

Performance

Getting Started

Eshu: Indentation Fixer for Eight Languages, Written in C

Eight languages, one tool

Why C?

How the scanner works

The hard parts

Perl: Is / division or regex?

XS: Two languages in one file

JavaScript: Template literals with nested interpolation

HTML: Script blocks need JavaScript rules

The CLI

The Perl API

Idempotent by design

What it does not do

Write the Perl module with `include_dir()`

Perl: Is `/` division or regex?