The Config Language That Was Already There: A Ballistics REPL Written in Lattice

A.C. Jokela — Sun, 02 Aug 2026 17:00:00 GMT

The Config Language That Was Already There: A Ballistics REPL Written in Lattice

Every calculator that gets used seriously eventually grows a configuration language.

It starts reasonably. You have a solver with fifteen inputs, and typing fifteen command-line flags every time is miserable, so you accept a config file. YAML, probably. Then someone wants two configs that differ in one field, so you add includes, or merge semantics, or a base: key. Then someone wants a parameter sweep, so you add a templating layer, or you tell them to write a shell loop that generates YAML. Then the YAML needs comments explaining which units each field is in, because YAML has no units and never will. Eventually the configuration language has variables, and interpolation, and a way to express "the same as above but 200 feet per second faster," and you have accidentally built a bad programming language with no debugger.

I have written that layer. More than once. This is about the time I refused to.

The result is a ballistics laboratory — a stateful REPL for exterior ballistics — written entirely in Lattice, the small interpreted language I've been building, driving the Rust ballistics engine I've also been building. The interesting part isn't that the two projects finally met. It's the specific thing I didn't have to build: there is no configuration format. The config language is Lattice, because the REPL is Lattice, and the experiment you're configuring is an ordinary value in the session.

You don't need to care about ballistics for the argument to land. Substitute your own domain with a solver at the bottom and a pile of parameters on top.

Lattice is free and open source at lattice-lang.org, and there is almost certainly a prebuilt binary for whatever you are reading this on. The current release ships 22 precompiled binaries across 11 platform targets — macOS, Linux, Windows, FreeBSD, OpenBSD and NetBSD, on x86_64 and aarch64, plus Linux on RISC-V — with checksums for all of them.

Each platform gets two builds: clat, the full interpreter with the REPL, formatter, debugger and documentation tooling, and clat-run, a runtime-only binary for executing compiled bytecode (655 KB on arm64 macOS). No runtime dependency to install; the ballistics laboratory in this post lives in the source tree under examples/ballistics_lab/.

The Shape of the Problem

Exterior ballistics is a good stress test for this idea, because the input surface is genuinely large and genuinely fussy.

A trajectory depends on the projectile (mass, diameter, length, drag model, ballistic coefficient), the rifle (sight height, twist rate and direction, muzzle height), the atmosphere (altitude, temperature, pressure, humidity, latitude), the wind (speed, direction, and whether you're modeling a vertical component), the shot itself (muzzle velocity, zero distance, maximum range, shooting angle, cant, azimuth), and the solver (method, time step, tolerances). Miss a unit conversion and you get an answer that is confidently, silently wrong.

Here is the state of a fresh session, printed by the laboratory's :show command:

Experiment: 175 gr match at 1,000 yards
  projectile           : 175 gr match
  mass                 : 175.00 gr
  diameter             : 0.31 in
  length               : 1.24 in
  drag model           : G7
  ballistic coefficient: 0.24
  rifle                : 24-inch match rifle
  sight height         : 1.50 in
  twist rate           : 8.00 in
  twist direction      : right
  altitude             : 273.40 yd
  temperature          : 59.00 F
  pressure             : 29.92 inHg
  humidity             : 50.00 %
  latitude             : +45.00 deg
  muzzle velocity      : 2700.00 ft/s
  maximum range        : 1000.00 yd
  zero distance        : 100.00 yd
  solver               : rk45

That is a lot of fields, and every one of them is a place where a config format would want a schema, a units convention, and a validation pass. This is exactly the shape of problem that produces a bespoke DSL.

What Running It Looks Like

The laboratory starts from a source checkout with a launcher that finds the interpreter and the engine:

./scripts/ballistics-lab.sh

ballistics-lab: backend=stack-vm, engine=/Users/alex/projects/ballistics-engine/target/release/ballistics
Ballistics laboratory — Lattice v0.6.4
Engine: .../ballistics-engine/target/release/ballistics
Type :help for commands or enter Lattice. Ctrl-D to exit.

The prompt accepts two kinds of input. Colon commands drive the session, and everything else is Lattice.

:solve runs the current experiment through the engine:

ballistics> :solve
Run: 175 gr match at 1,000 yards
  backend          : process-json-v1
  engine           : 0.30.1
  schema           : 1
  termination      : max_range
  actual range     : 1000.00 yd
  time of flight   : 1.71 s
  terminal velocity: 1145.95 ft/s
  terminal energy  : 510.19 ft-lb
  stability factor : 3.80

:at interrogates a single point on the solved trajectory:

ballistics> :at 300 yd
Observation
  distance: 300.00 yd
  time    : 0.37 s
  velocity: 2162.46 ft/s
  energy  : 1816.78 ft-lb
  drop    : +18.91 in
  windage : -6.71 in
  Mach    : 1.93
  flags   : none
Signs: drop/windage + above/right, - below/left

And :dope produces the table a shooter actually tapes to a rifle:

ballistics> :dope 100 600 100 yd
DOPE: 175 gr match at 1,000 yards
Distance (yd) | Drop (in) | Come-up (mil) | Velocity (ft/s) | Energy (ft-lb) | Time (s) | Mach
--------------+-----------+---------------+-----------------+----------------+----------+-----
       100.00 |     +1.50 |         -0.42 |         2513.37 |        2454.23 |     0.12 | 2.25
       200.00 |     +7.01 |         -0.97 |         2334.07 |        2116.56 |     0.24 | 2.09
       300.00 |    +18.91 |         -1.75 |         2162.46 |        1816.78 |     0.37 | 1.93
       400.00 |    +38.26 |         -2.66 |         1998.49 |        1551.71 |     0.52 | 1.79
       500.00 |    +66.33 |         -3.69 |         1841.19 |        1317.05 |     0.67 | 1.65
       600.00 |   +104.69 |         -4.85 |         1689.82 |        1109.39 |     0.84 | 1.51

There's a companion table for wind, which is where shooters actually lose their afternoons:

ballistics> :wind-card 200 600 200 yd
Wind card
Series | Trajectory                  | Wind (mph) | From (deg) | Distance (yd) | Windage (in) | Wind hold (mil)
-------+-----------------------------+------------+------------+---------------+--------------+----------------
  0.00 | 175 gr match at 1,000 yards |      10.00 |      90.00 |        200.00 |        -2.87 |           +0.40
  0.00 | 175 gr match at 1,000 yards |      10.00 |      90.00 |        400.00 |       -12.39 |           +0.86
  0.00 | 175 gr match at 1,000 yards |      10.00 |      90.00 |        600.00 |       -30.23 |           +1.40

Note the leading Series column, which is 0.00 throughout because there's one trajectory loaded. It's there because these tables are built to hold several trajectories at once and label each row with its source — the tabular output is a view over a collection of runs, not a formatted dump of the most recent one. That distinction is going to matter in a moment.

So far this is a competent CLI. Nothing here requires a programming language.

The Part That Requires a Programming Language

Now change something.

Not by editing a file and restarting. Not by passing a flag. By typing at the prompt, in the same language the laboratory is written in:

ballistics> let base = sessions.experiment_of(lab)
ballistics> let better = projectile("230 gr high-BC", gr(230), inches(0.308), 0.368, "G7", inches(1.55))
ballistics> let alt = experiment("230 gr high-BC load", better, base.rifle, base.atmosphere, base.winds, base.shot, base.solver)
ballistics> sessions.replace_experiment(lab, alt)
ballistics> :solve

Run: 230 gr high-BC load
  time of flight   : 1.44 s
  terminal velocity: 1601.26 ft/s
  terminal energy  : 1309.24 ft-lb

Same rifle, same atmosphere, same wind, same solver, same 1,000 yards. A heavier bullet with a better drag coefficient arrives sooner (1.44 s versus 1.71 s), still supersonic (1601 ft/s versus 1146), carrying two and a half times the terminal energy (1309 ft-lb versus 510).

Look at what that interaction actually required. base.rifle, base.atmosphere, base.winds, base.shot, base.solver — five subsystems reused verbatim, by name, because the experiment is a structured value and not a document. There was no merge semantics to design. No extends: key. No question about whether a null in the override means "unset this" or "inherit this." I destructured a record and rebuilt it with one field changed, which is a thing programming languages have been good at for fifty years.

That is the entire argument. The configuration language you were about to write is a worse version of a language you already have.

Units get the same treatment. gr(230), inches(0.308), fps(2700), yards(1000) aren't string tags to be parsed and validated — they're constructors producing distinct quantity values with SI internals and a preferred display unit. A YAML field called mass: 230 has to be documented as grains and validated at load time. gr(230) carries that with it, and the failure mode for passing a length where a mass belongs is an evaluation error, not a plausible-looking wrong trajectory.

"You Didn't Avoid Writing a Config Language, You Wrote a Whole Language"

This is the obvious objection and it deserves a straight answer rather than a clever one.

If the choice were write a YAML schema versus write a programming language, the YAML schema wins by a mile and it isn't close. Nobody should build a language to avoid building a config format. That trade is absurd.

But that wasn't the choice. Lattice already existed. It was not designed for ballistics, has no ballistics features, and would exist unchanged if I'd never written the laboratory. The marginal cost of using it here was zero, and the honest framing is not "I chose Lattice over Python" — it's "I had a language sitting there, and using it was cheaper than inventing a format." If you don't already have one, the answer is almost certainly Lua or Python, and the argument in this post applies to those just as well. The claim is about embedding a real language versus growing a fake one, not about which real language.

That said, two things about Lattice specifically turned out to fit better than I expected, and they're worth naming because they're the kind of thing you'd want from any candidate.

The first is the phase system. Lattice's central idea is that values start fluid and can be frozen into immutable crystal — it's what the language is about, and I've written before about making that promise actually hold. An experiment is precisely the kind of value that wants this: you assemble it, you hand it to a solver, and it must not change underneath the solver or between the run and the report that describes the run. In the domain layer that's a declaration, not a discipline:

export struct Projectile {
    name: fix String,
    mass: fix any,
    diameter: fix any,
    length: fix any,
    drag_model: fix String,
    ballistic_coefficient: fix Number
}

Every field is fix — immutable per-field, checked by the language. There are 192 such declarations across the laboratory's domain modules. In a language without that, the equivalent is a frozen dataclass, or a convention, or a code review comment; here it's a property of the type. A config format gets you immutability for free only because it's inert — it can't express computation at all. This gets you both.

The second is embedding cost. The laboratory ships with a runtime-only binary, clat-run, that is 655 KB on arm64 macOS — the full interpreter with tooling is 1.2 MB. Embedding CPython means shipping CPython; embedding Lua is genuinely small too, which is exactly why Lua keeps winning this category. The point isn't that Lattice is uniquely small, it's that "how much do I have to ship" is a real selection criterion for this kind of tool, and it's one a config format wins by default until you notice you've reimplemented variables.

So: not a triumph of language design over YAML. A case of the cheapest available option happening to be a real language, and the domain happening to want immutability badly enough that the language's central feature earned its keep.

The Boundary I Did Keep

There is exactly one place the laboratory refuses to be clever, and it's the interesting design decision in the project.

The physics does not run in Lattice. It runs in the Rust engine, in a separate process, over a versioned JSON protocol. The laboratory's README is blunt about this: it "does not add a ballistics intrinsic, native extension, or C ABI dependency to the language runtime." The backend reports itself in every run — backend: process-json-v1, engine: 0.30.1, schema: 1.

The obvious alternative was to bind the engine natively. I have the design document for it: a Rust extension at extensions/ballistics/ that statically links the crate and binds its Rust API. It's a real design, and it rejects the naive version for a good reason — the engine's C FFI takes a 26-field flat input struct, and mirroring that by hand through a generic FFI layer means keeping two definitions in sync forever, with a segfault waiting at the end of any drift. The document has been sitting at "Proposed. Architecture decided; pre-implementation" for a while now.

The process backend shipped instead, and the longer it runs the more I think the boring choice was right. A separate process gives you a version number you can print, a schema you can check, a crash that doesn't take the REPL with it, and an upgrade path where the engine and the language move independently. It also gives you an honest security boundary: the laboratory doesn't start the configured executable until you type :solve, and the launcher probes candidate engines with a non-solving capability check first.

The cost is process spawn per solve and JSON on the wire. For an interactive laboratory where a human types between solves, that cost is invisible. If I were solving in a tight loop, I'd be having a different conversation — and that's precisely when the extension design comes off the shelf.

There's a general principle hiding here. "Bind it natively" and "shell out to it" are usually presented as a performance question. They're mostly a coupling question, and the coupling bill arrives later than the performance bill does.

What Honesty Looks Like in the Output

The other thing that falls out of a real language: the tool can afford to tell you what it assumed.

Every solve reports its defaults explicitly, with JSON paths into the request:

Assumptions
  - default_applied: Aim azimuth defaulted to 0 rad. [$.shot.aim_azimuth_rad]
  - default_applied: Shot azimuth defaulted to 0 rad (north). [$.shot.shot_azimuth_rad]
  - default_applied: Shooting angle defaulted to 0 rad. [$.shot.shooting_angle_rad]
  - default_applied: Cant angle defaulted to 0 rad. [$.shot.cant_angle_rad]
  - default_applied: Target height defaulted to 0 m above the local ground datum. [$.shot.target_height_m]
  - default_applied: Solver time step defaulted to 0.001 s. [$.solver.time_step_s]
  - default_applied: Magnus effect defaulted to disabled. [$.effects.magnus]
  - default_applied: Enhanced spin drift defaulted to disabled. [$.effects.enhanced_spin_drift]

This is the sort of thing a config file makes harder, not easier. In a YAML world, an unspecified field is silently the default, and the only way to know what the default was is to read the source. Here, "I didn't specify a cant angle" and "the solver assumed zero cant" are two different facts and both are visible. Note the last two lines especially: Magnus effect and enhanced spin drift are off, and the tool says so rather than letting you assume a more sophisticated model than you got.

Runs also carry a verified: no flag, distinguishing "the solver produced numbers" from "the numbers were checked against a reference." A calculator that can't express that distinction encourages you to forget it exists.

Where It Actually Bit Me

I want to be honest about the failure mode of this approach, because I hit it while writing this post.

I ran the laboratory to capture the transcripts above, and :solve failed:

Error
  code: process_error
  message: undefined variable 'exec_argv'

exec_argv is the builtin that spawns the engine. My first read was that I'd shipped a real bug — that the process backend needed a function the bytecode VMs didn't implement, and the laboratory had only ever been tested on the tree-walking interpreter. That's a plausible bug, and it's the kind of bug that a two-implementation language invites.

It wasn't that. The launcher had resolved clat from my PATH and found an old v0.3.28 build sitting in Homebrew, from long before the VMs got that builtin. My local checkout's binary had been deleted by a sanitizer build earlier in the day, so the fallback kicked in. The banner had been telling me the whole time — Ballistics laboratory — Lattice v0.3.28 — and I hadn't read it.

Two lessons, both cheap in hindsight. First: print the version of every component, at startup, always. This tool does, which is the only reason the diagnosis took minutes instead of an evening. Second, and more pointed: a launcher that searches PATH for its own interpreter will eventually find the wrong one. Deterministic discovery order is documented in the README precisely because this is a known hazard, and it still got me, because I was the one who broke the invariant it depends on.

The nice part is that the failure was loud and local. The engine ran in another process; the missing builtin failed at the boundary with a specific name in the message. Had I bound the engine natively into the runtime, the equivalent mistake — a stale binary with an ABI that no longer matches — is not an error message. It's a crash, or worse, wrong numbers.

What This Buys, Concretely

Strip away the ballistics and the claim is small and testable: if your tool already embeds a scripting language, you should not also invent a configuration language.

What the laboratory gets for free, by that one decision:

Variables and reuse, because it's a language. Parameter sweeps are for loops, not a templating layer. A sweep over three ballistic coefficients isn't three config files and a shell script that concatenates three output files — it's a loop:

ballistics> let base = sessions.experiment_of(lab)
ballistics> let b = sessions.backend_of(lab)
ballistics> for bc in [0.24, 0.29, 0.34] {
              let p = projectile("bc ${bc}", gr(175), inches(0.308), bc, "G7", inches(1.24))
              let e = experiment("bc ${bc}", p, base.rifle, base.atmosphere, base.winds, base.shot, base.solver)
              let r = backends.solve_with(b, e)
              print("${bc} -> ok=${backends.solve_succeeded(r)}")
            }
0.24 -> ok=true
0.29 -> ok=true
0.34 -> ok=true

Three experiments derived from one base value, three solves, three results — as values in hand, which the analysis module can then interrogate. Worth being precise about the boundary: solve_with hands results back to you. It doesn't file them into the session's run history, which is what the colon commands manage; :solve and a programmatic solve are two different doors, and only the first one updates :compare's notion of "previous run." That's a seam, and an honest one to point at.

Comparison between the session's own runs is a session feature rather than a diffing tool over output files, because both runs are values the session is holding. Solve the 175 grain load, swap in the 230, solve again, and :compare interleaves them with per-row deltas:

ballistics> :compare
Trajectory comparison
Series | Trajectory                  | Distance (yd) | Velocity (ft/s) | Energy (ft-lb) | Delta velocity (ft/s) | Delta energy (ft-lb)
-------+-----------------------------+---------------+-----------------+----------------+-----------------------+---------------------
  0.00 | 175 gr match at 1,000 yards |         20.00 |         2662.10 |        2753.29 |                 +0.00 |               +0.00
  1.00 | 230 gr high-BC load         |         20.00 |         2674.94 |        3653.61 |                +12.84 |             +900.32
  0.00 | 175 gr match at 1,000 yards |         40.00 |         2624.49 |        2676.05 |                 +0.00 |               +0.00
  1.00 | 230 gr high-BC load         |         40.00 |         2650.01 |        3585.82 |                +25.52 |             +909.77

(Abridged — the real table runs every ten yards to the full range and carries drop, windage, Mach and time columns too. Series 0.00 is the baseline; deltas are each series minus it.)

Persistence is :save and :load over a JSON artifact, so the serialized form exists — but it's an artifact of a session, not the authoring interface. Nobody hand-writes it:

ballistics> :save "/tmp/rt2.json"
Saved experiment to /tmp/rt2.json
ballistics> sessions.replace_experiment(lab, experiment("DECOY load", decoy, ...))
ballistics> :show
  active experiment: DECOY load
ballistics> :load "/tmp/rt2.json"
ballistics> :show
  active experiment: 230 gr high-BC load

One detail worth knowing if you use this: :reset clears run state, not the experiment. After a reset the loaded experiment is still sitting there; what's gone is the solved-run history that :compare reads. It's the right split — you rarely want to retype an experiment just because you want to discard its runs — but the command name doesn't tell you that, and I only established it by resetting and then checking what survived.

And the failure modes get better. A typo in a config file is a schema violation at load time, at best. A typo at this prompt is an evaluation error with a line, immediately, in a session that stays alive so you can retype the line. Parse, evaluation, command, and engine failures are all reported without ending the session — which sounds like a small quality-of-life detail until you're forty lines into building an experiment.

The honest limitations, in the same spirit: the v1 REPL uses a portable input() loop, so there's no line editing, no history, no completion. It isn't available in WASM builds, because terminal input and process execution aren't. Those are real gaps, and they're the price of the portable path.

The Thing I Keep Relearning

I've built a fair number of tools that grew a configuration format, and the format was never the interesting part of any of them. It was always overhead — a parser, a schema, a validation layer, a units convention, a documentation page, and a slow drift toward Turing completeness that nobody planned and everybody regretted.

The ballistics laboratory has none of that, and it isn't because I was clever. It's because the language was already sitting there. The REPL is Lattice, so the experiment is a Lattice value, so configuring the experiment is writing Lattice, so there was never a moment where inventing a config format seemed necessary.

If your project has an embedded language and a config format, it's worth asking what the config format is actually buying you. Sometimes the answer is a real one — a stable serialization boundary, a format non-programmers can edit, a thing you can diff in review. But often the answer is that the config format came first, the scripting language came later, and nobody went back to ask whether both were still needed.

The laboratory ships in the Lattice repository under examples/ballistics_lab/, as of v0.6.4. It's an example in the literal sense: not a product, but a demonstration that a serious domain tool can be built in the language without escaping to C — which was the actual thing I wanted to find out.

TinyComputers.io (Posts about tooling)

The Config Language That Was Already There: A Ballistics REPL Written in Lattice