ESPLiveScript: Fix `__userDefined__` types as function parameters + (optional) add `Coord3D` built-in

[ewowi]

Summary

Two complementary improvements, in order of priority:

1. Bug fix (Fix A) — parseCreateArguments incorrectly applies register optimisation to struct-typed parameters, corrupting the target field that getVarType() uses for member lookup. This causes a parser crash ("member not found") for any user-defined struct used as a function parameter type.

2. New built-in (Fix B, optional) — Add Coord3D (three int fields: x, y, z) as a built-in type, analogous to CRGB. This is needed if you want to register C++ external functions that take a Coord3D parameter (e.g., addExternal("void setRGBCoord(Coord3D,CRGB)", ptr)).

Fix A alone is sufficient to allow scripts to write helper functions with user-defined struct parameters. Fix B additionally allows the C++ host to expose functions with Coord3D in their signature string.

---

Root cause of the crash

Symptom

member  not foudn in Coord3D
Guru Meditation Error: Core 0 panic'ed (LoadProhibited)
  #0 copyPrty(NodeToken*, NodeToken*) at NodeToken.h:1272
  #1 createNodeVariable(Token*, bool) at NodeToken.h:1544
  ...

Analysis

NodeToken uses the target field for two distinct purposes:

Context	target value	Meaning
Register-optimised local/param	small integer (0, 1, 2…)	register slot index
User-defined struct variable	EOF_TEXTARRAY (9999)	"no member selected; return whole-struct type"
User-defined struct member access	text index of member name	"look up this member in the struct"

In NodeToken::getVarType() (NodeToken.h:739):

if (type == TokenUserDefinedVariable)
{
    if (target != EOF_TEXTARRAY)
    {
        if (getTargetText()[0] == '@')
            return &_userDefinedTypes[_vartype];        // whole struct
        int i = findMember(_vartype, getTargetText());  // look up member
        if (i < 0) { printf("member not found"); return NULL; }  // CRASH
    }
    return &_userDefinedTypes[_vartype];                // whole struct (EOF case)
}

parseStatement (ESPLiveScript.h:1726) correctly guards register mode for primitive types only:

if (_for_depth_reg.get() <= _MAX_FOR_DEPTH_REG_2
    and (d == __float__ or d == __int__ or d == __s_int__
         or d == __uint8_t__ or d == __uint32_t__ or d == __uint16_t__))
{
    _is_variable_as_register.set(true);
}

But parseCreateArguments (ESPLiveScript.h:2075) has no such type guard:

if (_for_depth_reg.get() <= _MAX_FOR_DEPTH_REG_2)
{
    _is_variable_as_register.set(true);  // ← applies to ALL types including structs
}
if (_is_variable_as_register.get())
{
    _nd = NodeToken(_nd, defLocalVariableNodeAsRegister);
    _nd.target = _for_depth_reg.get();  // ← corrupts target for struct params!
    _for_depth_reg.increase();
}

When Coord3D p is declared as a function parameter and _for_depth_reg ≤ _MAX_FOR_DEPTH_REG_2, p's context entry gets target = 0 (or 1, 2…). Later, when p.x is parsed, getVarType() sees target != EOF_TEXTARRAY, calls findMember(k, all_targets.getText(0)), finds some unrelated text at index 0, and crashes.

Local variable Coord3D pos; works because parseStatement only enables register mode for the primitive types listed above — __userDefined__ is not in that list.

---

Fix A — parseCreateArguments: guard register mode by type (recommended)

File: ESPLiveScript.h

In parseCreateArguments, replace the unconditional register-mode check (around line 2075) with the same type guard used in parseStatement. The check must happen after parseType() has resolved the type.

The first parameter:

-        if (_for_depth_reg.get() <= _MAX_FOR_DEPTH_REG_2)
-        {
-            _is_variable_as_register.set(true);
-        }
+        if (_for_depth_reg.get() <= _MAX_FOR_DEPTH_REG_2)
+        {
+            varTypeEnum paramType = nodeTokenList.get().getVarType()->_varType;
+            if (paramType == __float__ or paramType == __int__ or paramType == __s_int__ or
+                paramType == __uint8_t__ or paramType == __uint32_t__ or paramType == __uint16_t__)
+            {
+                _is_variable_as_register.set(true);
+            }
+        }

The same fix must be applied in the while (Match(TokenComma)) loop (around line 2121), which processes subsequent parameters.

Effect

After this fix, scripts can write:

void helper(Coord3D p, CRGB c) {
    setRGBCoord(p.x, p.y, p.z, c);
}

without crashing. This works for any user-defined struct, not just Coord3D.

Why this is safe

• Struct-typed parameters cannot fit in a single Xtensa register; register optimisation for them is incorrect to begin with.
• parseStatement already excludes structs from register mode — this aligns parseCreateArguments with the same policy.
• Existing scripts are unaffected: primitive-type parameters continue to use register optimisation as before.

---

Fix B — Add Coord3D as a built-in type (optional, for external registration)

Fix A does not change how addExternal() parses its type strings. If the C++ host needs to register functions with Coord3D in the signature (e.g., "void setRGBCoord(Coord3D,CRGB)"), Coord3D must be a built-in TokenKeywordVarType.

1. asm_struct_enum.h — add __Coord3D__ to the type enum

 enum varTypeEnum
 {
     __none__,
     __uint8_t__,
     __uint16_t__,
     __uint32_t__,
     __int__,
     __s_int__,
     __float__,
     __void__,
     __CRGB__,
     __CRGBW__,
     __char__,
     __Args__,
     __bool__,
+    __Coord3D__,
     __userDefined__,
     __unknown__
 };

2. tokenizer.h — three locations

2a. Debug name array varTypeEnumNames[]

     "__bool__",
+    "__Coord3D__",
     "__userDefined__",

2b. _varTypes[] — add the type descriptor after __bool__

Coord3D has three int members (4 bytes each, loaded/stored with l32i/s32i):

+    {
+        ._varType = __Coord3D__,
+        .varName = "d",
+        ._varSize = 3,
+        .load    = {l32i, l32i, l32i},
+        .store   = {s32i, s32i, s32i},
+        .membersNames = {"x", "y", "z"},
+        .starts       = {0, 4, 8},
+        .memberSize   = {1, 1, 1},
+        .types        = {__int__, __int__, __int__},
+        .sizes        = {4, 4, 4},
+        .size         = 3,
+        .total_size   = 12,
+    },
+
 };   // end of _varTypes[]

2c. Keyword table — add "Coord3D" to the type-variable section

-#define nb_keywords 39
-#define nb_typeVariables 13
+#define nb_keywords 40
+#define nb_typeVariables 14
 string keyword_array[nb_keywords] =
     {"none", "uint8_t", "uint16_t", "uint32_t", "int", "s_int", "float", "void", "CRGB",
-     "CRGBW", "char", "Args", "bool", "external", "for", ...};
+     "CRGBW", "char", "Args", "bool", "Coord3D", "external", "for", ...};

"Coord3D" must be placed at index nb_typeVariables - 1 (the last slot before the non-type keywords), so the tokenizer assigns it TokenKeywordVarType and maps it to __Coord3D__ via its position in the array.

Effect of Fix B alone (without Fix A)

Coord3D becomes a TokenKeywordVarType, not a TokenUserDefinedVariable. This means it bypasses the __userDefined__ path entirely — including the register-mode collision — so the crash does not occur. Additionally, the host can call:

addExternal("void setRGBCoord(Coord3D,CRGB)", (void*)_setRGBCoord);

Notes

• int is 4 bytes on all ESP32 targets (Xtensa LX7 and RISC-V); total_size = 12 is correct.
• __userDefined__ and __unknown__ shift by one enum value. They are only referenced by name in the codebase, not by numeric literal, so no other changes are needed.
• The _varTypes[] array must stay indexed by varTypeEnum value; the new entry at position 13 maintains that invariant.
• No changes to ESPLivescriptRuntime.h or execute.h are expected — the existing struct member load/store machinery already handles both built-in struct types and user-defined types with l32i/s32i.

---

Recommendation

Apply Fix A first — it is a small, general bug fix that benefits all user-defined struct types. Apply Fix B if external function registration with Coord3D parameter types is needed on the host side.

With only Fix A, MoonLight scripts can write:

void helper(Coord3D p, CRGB c) {
    setRGBCoord(p.x, p.y, p.z, c);
}

With Fix B additionally, the MoonLight C++ side can expose:

static void _setRGBCoord(Coord3D pos, CRGB color) {
    gNode->layer->setRGB(pos, color);
}
// registered as: "void setRGBCoord(Coord3D,CRGB)"