Skip to content

LuaIota documentation

alexyzer edited this page Oct 16, 2026 · 4 revisions

Header

Iotas are represented as tables produced by serializing Iotas using lua types.

Some iotas may be restricted from deserialization by config, or processed through a validator registered through an API.

Automatically converted lua types

  • Numbers, booleans, null are converted to appropriate iotas.
  • TODO: strings should be converted to appropriate iota implementation, if available.
  • Lua lists (sequences) are converted to List Iotas, each element inside the list is parsed recursively.
  • ComputerCraft vectors are detected as tables only having x, y, z components and converted to vector iotas.

Iota deserialization restriction

All unknown iota types are restricted by default. This can be changed with Allow Deserialization of Unknown Iota Types setting.

Restricted iotas appear as Garbage in the stack.

To restrict malicious iotas, or allow trusted ones, include data/hexcc/allow_iota_deserialization.json file in your datapack or addon's resources.

Example file contents:

{
  "hexal:gate": false,
  "hexal:item": false,
  "moreiotas:string": true
}

<id>: false explicitly disables deserialization for given type.

<id>: true explicitly allows deserialization for given type.

If you omit the namespace, hexcasting will be taken as default.

{
  "gate": false,
  "item": false,
  "string": true
}

will become

{
  "hexcasting:gate": false,
  "hexcasting:item": false,
  "hexcasting:string": true
}

which would not be correct for any addon iotas.

Iota deserialization validators

If given iota type is allowed to deserize, it uses regular IotaType.TYPED_CODEC first, then pipes it through accociated iota validator.

Iota validator is simmilar to IotaType.validate(Iota, ServerLevel), but returns another iota instead as processing result.

To register one, use HexCCAPI.registerIotaDeserializationValidator.

##Built-in validators

  • EntityIota containing player reference will turn into GarbageIota unless Allow Deserialization of Player Iotas setting is true.
  • Contents of ListIota will be validated.
  • PatternIota containing back-turns will turn into GarbageIota unless Allow Deserialization of Invalid Pattern Iotas setting is true.
  • ContinuationIota's frames will be inspected and validated. ContinuationIota containing non-vanilla frames will turn into GarbageIota.
    • ContinuationIota validator extension is planned.

Clone this wiki locally