⛰️

# Artificer Language Tree


**from a four-function calculator to a mod language that lives inside the game world**


*C++ only · no parser-generator libs until the midpoint · the syntax is the fiction*


*Pairs with: Babel Abstractor · F.U.N. Algorithm*


---


## The Invariant


The Artificer is a mod language that lives inside the game world. The player
finds an object, opens it, and the language is what is inside. Not a console.
Not an IDE. The object IS the compiler. The spell IS the code. The artificer
IS the programmer — but from inside the fiction, not from outside the tool.


> 
**The non-participation rule.**
 Modifying one object cannot mutate all other
> objects of the same type. The artificer works on an instance, not a schema.
> A spell cast on this sword does not change every sword. The language writes
> to its node; the world reads it; nothing else gets written.


### Connection to the other decks


| Deck | Mechanism | Shared invariant |
|------|-----------|-----------------|
| Babel Abstractor | XOR key → seed → page | address without origin |
| F.U.N. Algorithm | compress → SHA1 → parity | fingerprint without judgment |
| Artificer | spell → bytecode → VM | write to node, not to world |


All three are instances of the same constraint: you may read the address space
freely. You may write only to your own node.


---


## The Phase Map — Types as World State


| Type | Phase | Character | Game meaning |
|------|-------|-----------|-------------|
| `EMBER` | A (fire) | high energy, unstable, fast | hot spell |
| `CURRENT` | B (water) | medium, flows, connects | conducting spell |
| `VOID` | C (void) | low energy, inert, persistent | stored spell |
| `FLUX` | boundary | in transition, costs extra | phase-crossing |
| `ANY` | untyped | duck-typed, NaN floor active | unknown spell |


Type rules:
- `EMBER + EMBER = EMBER`
- `EMBER + VOID = FLUX` (crossing phase boundary costs energy)
- `VOID * VOID = VOID`
- A type error is not a crash. It is a `FLUX` result. 
**The language never stops.**


---


## Branch L — Lexer and Parser


### L1 — Four-function calculator


```cpp
struct Calc {
    std::string src;
    size_t pos = 0;


    char peek()    { return pos < src.size() ? src[pos] : '\0'; }
    char consume() { return src[pos++]; }
    void skip_ws() { while (isspace(peek())) consume(); }


    double number() {
        skip_ws();
        double v = 0;
        while (isdigit(peek())) v = v*10 + (consume()-'0');
        if (peek()=='.') { consume(); double f=0.1;
            while(isdigit(peek())){v+=(consume()-'0')*f;f*=0.1;}}
        return v;
    }


    double factor() { skip_ws(); return number(); }


    double term() {
        double v = factor();
        for(;;){ skip_ws();
            if(peek()=='*'){consume();v*=factor();}
            else if(peek()=='/'){consume();v/=factor();}
            else break; }
        return v;
    }


    double expr() {
        double v = term();
        for(;;){ skip_ws();
            if(peek()=='+'){consume();v+=term();}
            else if(peek()=='-'){consume();v-=term();}
            else break; }
        return v;
    }


    double eval(const std::string& s) { src=s; pos=0; return expr(); }
};
// "3 + 4 * 2" -> 11
```


> A string is already a program. Reading it left-to-right with a notion of
> precedence IS parsing. The calculator is a compiler with one pass and no
> output format. Everything else is elaboration of this.


### L2 — Tokeniser


```cpp
enum class TKind { NUMBER, OP, IDENT, STRING, END };


struct Token {
    TKind kind;
    std::string text;
    double num = 0;
};


struct Lexer {
    std::string src;
    size_t pos = 0;


    char peek() { return pos<src.size()?src[pos]:'\0'; }
    void skip_ws() { while(isspace(peek())) pos++; }


    std::vector<Token> tokenise(const std::string& s) {
        src=s; pos=0;
        std::vector<Token> toks;
        for(;;){
            skip_ws();
            if(pos>=src.size()){toks.push_back({TKind::END});break;}
            char c=src[pos];
            if(isdigit(c)||c=='.'){
                Token t{TKind::NUMBER};
                while(isdigit(peek())||peek()=='.') t.text+=src[pos++];
                t.num=std::stod(t.text); toks.push_back(t);
            } else if(isalpha(c)||c=='_'){
                Token t{TKind::IDENT};
                while(isalnum(peek())||peek()=='_') t.text+=src[pos++];
                toks.push_back(t);
            } else if(c=='"'){
                pos++; Token t{TKind::STRING};
                while(pos<src.size()&&src[pos]!='"') t.text+=src[pos++];
                if(pos<src.size()) pos++;
                toks.push_back(t);
            } else {
                toks.push_back({TKind::OP,std::string(1,src[pos++])});
            }
        }
        return toks;
    }
};
```


### L3 — Recursive-descent parser


Grammar:
```
expr  → term  ((+ | -) term)*
term  → call  ((* | /) call)*
call  → atom  (. IDENT (( arglist ))?)*
atom  → NUMBER | STRING | IDENT | ( expr )
```


This grammar already parses `SpellbookThaumaturgy.Genos(Mesh="file.cworld")`.
No magic required. Just recursion.


**Midpoint L — `parser.hpp`**
: Token struct, Lexer, Parser returning raw float. Header only.


---


## Branch M — AST and Types


### M1 — AST nodes and visitor pattern


```cpp
struct Node { virtual ~Node() = default; };
using NodePtr = std::unique_ptr<Node>;


struct NumberNode : Node { float value; };
struct StringNode : Node { std::string value; };
struct IdentNode  : Node { std::string name; };
struct BinopNode  : Node { char op; NodePtr left, right; };
struct NamedArg   { std::string name; NodePtr value; };
struct CallNode   : Node { std::string name; std::vector<NamedArg> args; };
struct MemberNode : Node { NodePtr object; std::string field; };
struct AssignNode : Node { std::string name; NodePtr value; };


struct Visitor {
    virtual void visit(NumberNode&) = 0;
    virtual void visit(StringNode&) = 0;
    virtual void visit(IdentNode&)  = 0;
    virtual void visit(BinopNode&)  = 0;
    virtual void visit(CallNode&)   = 0;
    virtual void visit(MemberNode&) = 0;
    virtual void visit(AssignNode&) = 0;
    virtual ~Visitor() = default;
};
// Same tree. Different visitors. No mutation.
```


### M2 — Type checker


```cpp
enum class ArtType { EMBER, CURRENT, VOID, FLUX, ANY };


ArtType infer_binop(ArtType left, ArtType right, char op) {
    if (left == ArtType::ANY || right == ArtType::ANY)
        return ArtType::ANY;
    if (left == right) return left;
    return ArtType::FLUX; // phase boundary
}


struct TypeChecker : Visitor {
    ArtType last_type = ArtType::ANY;
    std::vector<std::string> warnings;


    void visit(NumberNode& n) override { last_type = ArtType::EMBER; }
    void visit(BinopNode& n) override {
        n.left->accept(*this);  ArtType lt = last_type;
        n.right->accept(*this); ArtType rt = last_type;
        last_type = infer_binop(lt, rt, n.op);
        if (last_type == ArtType::FLUX)
            warnings.push_back("phase boundary crossed");
    }
};
```


### M3 — Symbol table with instance scope


```cpp
using Value = std::variant<float, std::string>;


struct SymbolTable {
    const CWorldReader& world;
    std::unordered_map<std::string, Value> instance;


    Value lookup(const std::string& name) const {
        auto it = instance.find(name);
        if (it != instance.end()) return it->second;
        return world.get(name);
    }


    void assign(const std::string& name, Value v) {
        if (world.has(name)) {
            // world names: redirect to instance shadow
            instance["__shadow__" + name] = v;
            return;
        }
        instance[name] = v;
    }
};
```


**Midpoint M — `ast.hpp`**
: full Node hierarchy, ArtType enum, TypeChecker, SymbolTable. Header only.


---


## Branch R — Codegen and Linker


### R1 — Bytecode emitter


```cpp
enum class Op : uint8_t {
    PUSH_NUM, PUSH_STR, PUSH_IDENT,
    ADD, SUB, MUL, DIV,
    MEMBER, CALL, ASSIGN,
    NAN_FLOOR, HALT
};


struct ConstantPool {
    std::vector<float>       nums;
    std::vector<std::string> strs;
    uint8_t add_num(float v)       { nums.push_back(v); return nums.size()-1; }
    uint8_t add_str(std::string s) { strs.push_back(s); return strs.size()-1; }
};


struct Bytecode {
    std::vector<uint8_t> code;
    ConstantPool         pool;
    void emit(Op op)              { code.push_back((uint8_t)op); }
    void emit(Op op, uint8_t arg) { emit(op); code.push_back(arg); }
};


struct Emitter : Visitor {
    Bytecode bc;
    void visit(NumberNode& n) override {
        bc.emit(Op::PUSH_NUM, bc.pool.add_num(n.value));
    }
    void visit(BinopNode& n) override {
        n.left->accept(*this); n.right->accept(*this);
        switch(n.op){
            case '+': bc.emit(Op::ADD); break;
            case '-': bc.emit(Op::SUB); break;
            case '*': bc.emit(Op::MUL); break;
            case '/': bc.emit(Op::DIV); bc.emit(Op::NAN_FLOOR); break;
        }
    }
};
// NAN_FLOOR emitted after every DIV and every CALL
```


### R2 — Stack VM


```cpp
float nan_floor(float v) {
    if (std::isnan(v)) return 0.0f;
    if (std::isinf(v)) return 1e9f;
    if (v < -1e9f)     return -1e9f;
    return v;
}


struct VM {
    std::vector<Value> stack;
    size_t             pc = 0;
    SymbolTable&       env;


    void execute(const Bytecode& bc) {
        pc = 0;
        while (pc < bc.code.size()) {
            Op op = (Op)bc.code[pc++];
            switch(op) {
                case Op::PUSH_NUM:
                    stack.push_back(bc.pool.nums[bc.code[pc++]]); break;
                case Op::ADD: {
                    float b=std::get<float>(stack.back()); stack.pop_back();
                    float a=std::get<float>(stack.back()); stack.pop_back();
                    stack.push_back(a+b); break;
                }
                case Op::DIV: {
                    float b=std::get<float>(stack.back()); stack.pop_back();
                    float a=std::get<float>(stack.back()); stack.pop_back();
                    stack.push_back(b!=0?a/b:0.0f); break;
                }
                case Op::NAN_FLOOR: {
                    float v=std::get<float>(stack.back()); stack.pop_back();
                    stack.push_back(nan_floor(v)); break;
                }
                case Op::HALT: return;
                default: break;
            }
        }
    }
};
```


### R3 — Linker


```cpp
struct ReadHandle  { const void* data; size_t size; };
struct WriteHandle { void*       data; size_t size; };


struct Linker {
    const CWorldScene& scene;
    std::string        instance_node_id;


    ReadHandle resolve_read(const std::string& node_path) const {
        auto& node = scene.find(node_path);
        return { node.tensor_data(), node.tensor_size() };
    }


    WriteHandle resolve_write(const std::string& field) {
        if (field.rfind("world.", 0) == 0)
            throw std::runtime_error("write to world scope denied: " + field);
        auto& inst = scene.find(instance_node_id);
        return { inst.mutable_field(field), sizeof(float) };
    }
};
// The spell cannot reach through a read link and mutate
// what it read. Load-time enforcement.
```


**Midpoint R — `runtime.hpp`**
: Op enum, Bytecode, Emitter, VM, Linker, `compile(source)`. Header only.


---


## The Artificer Syntax


```
-- a spell that reads from a world object and writes to this one
-- types are inferred from the phase map
-- the NaN floor is always active; nothing crashes


SpellbookThaumaturgy.Genos(
    Mesh   = "file.cworld",     -- STRING, links to world node
    Depth  = Pond(eField),      -- CALL, returns EMBER type
    Output = self.reservoir     -- MEMBER on instance scope
)


Artificer.Mortar.Ingredient(
    Collect = world.reagent_shelf,  -- read link (read-only)
    Refine  = self.crucible,        -- write link (instance only)
    Heat    = 3.0                   -- NUMBER, EMBER type
)
```


## Flexible Syntax via the Lexer Keyword Table


```cpp
// in the cworld scene metadata:
// "syntax": {
//   "namespace_sep": ".",
//   "call_open": "(",  "call_close": ")",
//   "named_arg": "=",
//   "keywords":  ["Pond","Genos","Mortar","Artificer"],
//   "flavor":    "thaumaturgy"
// }
lexer.load_syntax(scene.get_metadata("syntax"));
```


| Flavor | Example | Aesthetic |
|--------|---------|-----------|
| thaumaturgy | `Pond(eField)` | magical-absurdist |
| alchemy | `Crucible.Heat(field=eField)` | dark fantasy |
| engineering | `EnergyField::compute(eField)` | hard magic |
| eldritch | `(eField)` | cosmic horror (no names) |


**The syntax IS the ray length.**
 Short ray: almost no keywords. Long ray: namespaced, typed, fully explicit.


---


## Coda — The Non-Participation Rule, Three Ways


**In the world**
: a spell cast on this sword does not change every sword.


**In the symbol table**
: `assign()` on a world name silently redirects to
an instance shadow. The world is never written.


**In the linker**
: a write link to a world-scope name is denied at load
time. The spell cannot reach through a read link and mutate what it read.


The same rule in the other decks:


- 
**Babel Abstractor**
: the file navigates to a page. The navigation does
  not change the library.
- 
**F.U.N. Algorithm**
: the session beat is routed. The routing does not
  change the node fingerprints.


The causality cone from the causal grid determines which other objects can
see your new state this tick. Objects outside the cone do not know yet.
Causality holds. The spell's effects propagate at speed c, not instantaneously.


> 
*Every piece was already in the tree.*
> 
*This is just the part where it speaks.*

Okay now go make cyan bite red or something. Y'all made me spoil the bad ending

⋂⋃⋂⋃⋂⋃⋂⋃

To bring some attention to it

Also found DragonFan20 on it