New Scripting

[youhide]

I am going to start the new scripting stuff, something similar to the Sphere

[youhide]

Design sketch for the native engine, and two things worth deciding together before any parser gets written. The case for doing this at all, with the numbers, is in #7.

Name: Shardscript, extension .shard, crate openshard-script.

The part inherited from Sphere is the content model: itemdef / chardef keyed by the client's own graphic and body ids, triggers declared inside the def, typedef so one behaviour covers thousands of defs by item type, named event bundles attachable to an individual object at runtime and persisted, and a layered dispatch chain (instance → def bundle → typedef → def → global) where a return pre-empts the rest.

What is not inherited, and why: <...> textual substitution is unparseable by construction — < is interpolation-open, less-than and half of shift at once, and Source-X resolves it with commented heuristics ("I guess i have sufficient proof: skip, it's a << operator"); there is no operator precedence, so 2*3+1 is 2*(3+1) and the scriptpack compensates by parenthesising everything; loops re-seek the file and re-substitute every line on every iteration; six overlapping storage namespaces (TAG/TAG0/CTAG/LOCAL/VAR/DEF) differ only by prefix and by persistence, so choosing wrong is a bug that shows up after a restart; and [FUNCTION] has no parameters, only ARGN1..ARGN3. Per CLAUDE.md, .scp is never parsed at runtime and there is no source compatibility — the model is inspired, the language is ours.

---

Question 1 — what does the surface syntax look like?

Same content model either way. This is purely what a pack author types.

(a) modern blocks

itemdef HEAL_POTION {
    name = "a greater heal potion"
    type = potion

    on dclick(by) {
        by.heal(25)
        self.consume(1)
        handled
    }
}

(b) Sphere-shaped INI

[ITEMDEF 0f0c]
NAME=a greater heal potion
TYPE=t_potion

ON=@DClick
    SRC.HEAL 25
    CONSUME 1
    RETURN 1

(c) hybrid — Sphere-shaped headers and KEY = VALUE properties, modern braced trigger bodies

[ITEMDEF 0x0f0c]
NAME = "a greater heal potion"
TYPE = potion

ON @DClick(by) {
    by.heal(25)
    self.consume(1)
    handled
}

(a) is my preference: the line-oriented KEY=VALUE shape is precisely what forced Sphere's worst parser hacks, and a real grammar buys file:line:col diagnostics with a caret span. (b) is the one a Sphere admin opens and can read immediately, which is a real migration argument and not a small one. @enomado — which reads better to you?

For scale, this is what the loot table looks like under (a), replacing loot.js:

chardef 0x0032 {
    name  = "an orc"
    fame  =  300
    karma = -300

    on corpse(corpse) {
        corpse.add(GOLD,          amount: rand(20, 60), stacks: true)
        corpse.add(DAGGER,        chance: 40%)
        corpse.add(LEATHER_CHEST, chance: 15%)
    }
}

chance: is a named argument on the builtin, so the roll happens host-side against the world's seeded rng — one crossing instead of a Math.random guard, and pack loot joins the replayable stream.

And the 25,107-line generated decoration file becomes a table block with a declared header — one row of integers per line, diffable when the converter re-runs, and never seen by the interpreter:

deco on felucca [graphic, x, y, z, hue?] {
    0x108F  5552  1864   11
    0x0FAC  5556  1826  -12  0x0481
}

That is the key to the whole design: op_register_quests, op_register_regions, op_register_spawner, op_register_npc_speech, op_decorate and op_stock stop being calls and become declarative blocks, so the VM never runs for ~25,000 of the pack's 28,633 lines.

---

Question 2 — does a trigger get to say no, and when?

Today's hooks return nothing: the engine calls onEvent / onTick and discards the result (crates/server/scripting/src/engine.rs:282). Sphere's RETURN 1 — "the engine does not do its default" — is the thing that makes a def language worth having, and adding it means a synchronous verdict from inside the world's tick:

typedef door {
    on dclick(by) {
        if self.locked and not by.carries(self.key) {
            refuse "It is locked."
        }
    }
}

Two verbs rather than Sphere's overloaded integer, because "I implemented this myself" and "you may not do this" are different intents that want different messaging:

• fall off the end → the chain continues and the core's default action runs;
• handled → stop the chain, suppress the default;
• refuse "msg" → stop the chain, suppress the default, and tell the actor why.

(Sphere's actual rule is that any return other than 0 or falling-off-the-end halts the chain, so RETURN 2 means a third thing no script author can see in the syntax. Two named verbs remove that.)

The cost is that this touches crates/server/world/src/tick.rs, the most load-bearing code in the repo. The plan is to land the port inert — an empty Option on WorldState, so a scriptless shard pays one null check and every existing tick test is untouched — then one call site per PR:

1. ItemUse — Sphere's @DClick, the trigger packs reach for most, one call site, and the seam already exists (the pack sees ItemUsed after the core has acted today);
2. Speech — before the line is broadcast, so a pack can own a keyword;
3. MobileUse — before a shop opens;
4. Step — highest frequency, so it goes after a link-time trigger index has been proven to cost nothing when unused;
5. Damage — first one that wants an amending verdict, so it goes last and the enum grows a variant when it does.

Options: all five phased as above (my preference), ItemUse only for now with the rest backlogged, or defer the whole thing — port the language first at exact behavioural parity with today and add the veto in a second pass.

---

Everything else is already decided

• DenoEngine goes behind #[cfg(feature = "deno")] and the engine is chosen by pack shape — a directory with pack.toml → Shardscript, .js → Deno — so both packs can sit side by side and the shard plays at every step. V8 is deleted in the last PR.
• The migration is proved by a round-trip, per docs/architecture.md § "Converting is verified by round-tripping": load the old pack under DenoEngine and the new one under ShardEngine, drain take_commands() from both, sort, compare. Identical Vec<Command> or the port is not done. That test is worth more than every unit test in the plan.
• Values: int (i64), bool, str, list, map, handle, none. No floats (every number here is a graphic, a body, a hue, hits, a skill in tenths — the pack's one float is chance: 0.4, and 40% says it better) and no closures (the pack's only use of first-class functions is Pack.itemUse[graphic] = fn, which is the def system). Dropping closures deletes the whole GC design problem: copy-on-write Rc values, no cycles, no collector.
• Two mutable namespaces and no script globals at all: var is a local that dies with the trigger, tag is declared in a def and stored as a saved component. That is docs/architecture.md's existing rule — "if a binding must outlive a reboot, it is a saved component, not a map in a script" — made mechanical, and it deletes globalThis.Pack, the eleven registry-guard preambles, and the const ops collision hazard quests/quests.js:24 documents.
• Bytecode rather than a tree-walk, chosen for four reasons that are not speed: the compile pass is where the link checks live, fuel is one counter in the dispatch loop, hot reload becomes a pointer swap, and the constant pool is where the big tables go.
• A trapped trigger enqueues nothing — the outbox takes a savepoint on entry and truncates on trap. Today a throwing hook keeps whatever it already pushed, so a half-run hook half-applies.

[enomado]

Hey friend. Sorry in advance if this reads like AI slop — my English isn't great, so I'm having a model translate what I write, faithfully, without adding anything of its own. So it's actually me, worth reading through rather than skimming.

tldr: you can always take LUA

I got a bit sidetracked on the client, yeah — it felt like the right place to start, and I'm building a lighting engine. Maybe down the line something like FOnline or FTactics becomes possible. Honestly, once I started on this I realized the whole thing is really groundwork for a bigger, more sensible game. For example I detached the camera, made it inertial, free — like in Diablo — I've got a lot of open questions around the camera. Later, tiles could be dropped entirely. Everyone could run at a different speed, and horses could be added to the world that run at different speeds too. Spells could stay uninterrupted if you take three steps but break if you take five, mounted archery skills — anyway, all of that is appealing, and I don't see the point in staying tied to the Ultima protocol, at least not a year from now. So yeah, I got sidetracked, but as soon as I've got the client handled I'll get back to the shard. That was an unnecessary aside in a public repo, but whatever — for now it's just the two of us.

On all this scripting stuff in general — I've been watching the history of Ultima shards, and it's all pretty sad. 15 years ago I installed Sphere and found junk where scripts should have been. Then I looked at how RunUO scripts and that was more interesting, but still not it. I have zero experience scripting servers myself, but I did try writing advanced client-side scripts, and I quickly realized the whole model doesn't work — and it's the same model RunUO uses — it's very imperative. A script acts on behalf of actors. The problem with scripts was that they just executed something, but really, at every moment they needed to be watching whether the character is hungry, whether there's danger nearby. That's a hierarchical state machine.

You're sensing correctly that scripts aren't really needed and should be as dumb as a set of Sphere-style declarations, but I feel something different. They should be some kind of pure, total functions of state — some kind of state machines. I can't fully put it into words yet, but I want to try a completely different way of writing them — in formal logic, with something like Alloy.

I'm too much of an idealist on this question. For me there's still an open boundary: go full ECS, or leave part of the logic imperative? The scripts, their syntax — that's secondary. For now I want to put as much logic as possible in Rust. But all of this is going to be slow, maybe stretch on for years. For now I just want to build the shard of my dreams. What I'm really aiming at is a client that runs on WASM without downloading 3 gigabytes — dynamic loading, basically. And beyond that I'll just keep building the shard of my dreams. Whoever wants to can share ideas

[youhide]

Read it properly, don't worry — and thanks for writing it out at length. Two things came out of digging into this that change the question, so I want to put them to you before answering the syntax one.

First: you're right about the model, and about a part I hadn't looked at

The built-in brain already is what you describe. ai::think_one re-derives everything from world state each beat — no accumulated state, no state enum, just a priority ladder evaluated from scratch: flee, kite, melee, chase, hunt, wander. That's a total function of state already.

What is not that is the scripted brain. op_control marks a mobile Scripted, the tick skips the built-in brain (world/src/tick.rs:1228), and onTick gets handed a serial and nothing else. No step_toward, no chase, no flee — those are Rust-side and not exposed. So a scripted brain reimplements pathfinding by hand out of op_position and op_move. That is exactly the "a script acts on behalf of actors" failure you're pointing at, and it's real. I had not looked there, and the plan I wrote doesn't touch it.

Worth adding: the engine has already re-derived your "continuously watching" idea four separate times, with no abstraction over any of it —

• tick/status.rs:201 — gold, armour, weight, followers, diffed against last_status
• refresh_light — light level against last_light
• tick.rs:714 — quest objectives, counted from the backpack
• tick.rs:686 — trades that stopped being valid

Each one carries a comment explaining that the alternative, a call beside every mutation, rots. quest.rs:43 says it outright: "Counted from the backpack rather than announced, because nothing in the engine emits an event when an item changes hands." Your instinct is in the code four times already, unnamed. If we ever build the thing you're describing, that's where it starts, and it's engine-side Rust — which is where you said you want the logic anyway.

On "go full ECS" — I think that boundary is narrower than it looks. Registry (common/entities/src/registry.rs:81) is already a sparse-set ECS: type-erased columns, generational handles, query/query2/for_each2_mut, no unsafe, no external dependency. architecture.md:245 explains why sparse sets and not archetypes — components churn constantly here, and archetypes would move a whole row on every change. What's missing is a scheduler, and that's a deliberate refusal: the tick is single-threaded because determinism and replay are the point. And the numbers say there's nothing to schedule around — 10,000 thinking creatures cost 2.23 ms of a 50 ms tick, 0.09 ms with LOD on. So I don't think that fork is as load-bearing as it feels.

Second, and this is the one I want your call on

The pack is 98.6% data. 28,219 of its 28,633 lines come straight out of tools/convert-servuo.cjs. The hand-written logic is 414 lines across four files. Seventeen of the engine's thirty-five ops are ever called, and six of those seventeen are bulk registration.

Now — the repo already keeps exactly this kind of ported ServUO data in-tree:

crates/server/crafting/data/   carpentry 51KB · tailoring 37KB · tinkering 32KB
                               blacksmithy 30KB · alchemy 9.7KB    (163KB total)
crates/server/state/data/      skills 13KB · body_types · creature_names
                               creature_sounds · harvest_tiles · mounts
crates/server/npc/data/        names.json

Four build.rs, five data/ directories, and architecture.md:153 states it as a rule: "A table of more than a hundred rows belongs in crates/<group>/<crate>/data/ as JSON, with a build.rs that emits the const before the crate compiles."

So craft recipes are gameplay content living in the repo, compiled. Spawns and decoration are gameplay content living in a second repo, as JavaScript, behind a V8. Same kind of data, opposite sides of a line I can't find a principled reason for. One of the two is in the wrong place, and it isn't crafting.

If the generated data moves in-tree the way crafting already did, the pack is 414 lines — and nobody builds a language for 414 lines. Those 414 become ordinary systems in the domain crates as fn(&mut WorldState), which is what architecture.md:67 already says a gameplay rule should be. Then the whole scripting crate and its bridge go — about 4,700 lines — and with them:

• CI stops excluding the crate (it's excluded today only because deno_core downloads a prebuilt V8)
• the workspace MSRV comes off 1.88
• no V8 download, no MPL-2.0 in the tree
• validation becomes rustc, which is strictly stronger than the link checker I was proposing to write
• one rng stream instead of two, so the loot.js determinism exemption disappears
• no interpreter to bound, so no step budget to build

That is "put as much logic as possible in Rust" taken literally.

What it costs, honestly, because it isn't free: hot reload dies for logic — today you edit a spawn and it takes effect on save, and that goes away. And writing content then requires Rust. The first one arguably wants the planned map editor rather than a text file anyway. The second has no workaround.

So the real question

Is OpenShard an engine other people deploy with their own content, or the shard we want to play?

If it's the first, the pack is a product requirement, and I'll do the declarative content layer first and a language for the leftovers later. If it's the second, the pack is overhead costing us V8, CI, the MSRV and an entire language, to serve a content author who doesn't exist yet.

You wrote "for now I just want to build the shard of my dreams" — I read that as the second, but I'd rather you say it than have me assume it and delete a repo on inference.

Either way the syntax question can wait. Under one of those two answers it stops mattering entirely.

[youhide]

And my own position, so you're not guessing at it while you think it over.

I optimise for the architecture. Whatever leaves the engine cleaner wins — so if killing the pack makes it better, I'd rather kill the pack. 🙂

And I think it does. One place for gameplay data instead of two, with the same rule applied to spawns and decoration that we already apply to craft recipes and skills. Content validated by rustc instead of by a checker we'd have to write and maintain. One rng stream. No V8, no MSRV pin, no crate sitting outside CI. That's not a small tidy-up, it's a whole category of machinery we stop owning.

I'm accepting the cost that comes with it, openly: content then requires Rust, and hot reload of logic goes away. I'm fine with both for where we are now. If a third party ever turns up wanting to write content without compiling, that's the day we bring a scripting layer back — and it'll be a better one for having been designed against a real user instead of an imagined one.

But it's your project too, and you're the one arguing the model question, so say if you see it differently. Not in a hurry.

[enomado]

right now i'm just in full YOLO mode "why there is no healer near" and "why cooking strove is half tile". today i try to commit my changes

[enomado]

but i think all scripts should be ported in rust lol

[youhide]

That settles it then — pack dies, everything goes to Rust. 👍

Nobody turned up in #18 either, so there's no content author out there we'd be stranding. Silence was a fair answer.

And funnily enough your two complaints make the case better than my wall of text did. "Why is there no healer near" and "why is the cooking stove half a tile" are both pack content — a missing spawn and misplaced decoration. Right now fixing either means editing a second repository. Once the data is in-tree they're a JSON edit and a rebuild, in the same place you're already working.

One practical thing, since you're pushing to main directly and I'm about to move ~28k lines and delete a crate. Let's not collide. The order I'd go in:

1. Data in-tree first, crate by crate, converter retargeted to emit JSON into data/ with a build.rs — the same shape crafting/data/ already has. Spawns, regions, vendors, speech, escorts, then decoration last since it's 25k lines on its own. The shard keeps running off the pack the whole time; nothing is deleted yet.
2. Equivalence test before anything is removed: a shard seeded from in-tree data must produce the same world as one seeded from the pack — same spawners, same decoration, same vendors, compared as sorted command streams. If that doesn't match, the port isn't done.
3. The 414 lines of logic become systems in the domain crates.
4. Then scripting and its bridge go — 4,926 lines as of today — and CI stops excluding the crate, the MSRV comes off 1.88, V8 and MPL leave the tree.

Each of those is its own PR, and the shard boots and plays after every one.

Mostly what I need from you: shout if you're deep in a file I'd be touching. I'll stay out of client/ entirely — that's yours right now, and the lighting/camera work looks great from over here. If you'd rather I hold off entirely until you've landed the client pass, say so and I'll wait; there's no rush on my side.

[enomado]

bro its dead game. I go throught some chats - describing - we are creating best fast uo experience. no one cares. I want to bootstrap map editor later.

best we can do is to create a working shard, then generalize it if anybody wants.

I think you can touch everithing. just try to push changes asap. and i think weekend is yours. if i will do something - it would be some skills - lumberjack, archery, dunno. anyway, i pushed all my work and its fully synced rn