Worldforge API Reference

Practical guide

Preserve compatible state across reload

Design package state so transactional reload can validate a replacement VM and retain only version-compatible host-owned settings.

Procedure

  1. Keep durable settings in the manifest-declared settings schema instead of hidden globals.
  2. Declare a settings schema version and provide defaults for every field.
  3. Implement validate, initialize, suspend, and shutdown callbacks with bounded work and no owner mutation.
  4. Request reload through the compiled recovery action at a frame boundary.
  5. If validation fails, inspect diagnostics while the prior VM and composition graph remain active.

Example

function validate_package()
    assert(package_info.id == "worldforge.resource-counts")
    assert(type(settings.enabled) == "boolean")
end

function initialize_package()
    initialized = true
end

function suspend_package()
    assert(initialized)
end

function shutdown_package()
    initialized = false
end

Constraints and recovery

Related symbols

Project references