Skip to main content

Capture UI State (LCC.capture_ui_state)

Signature​

local state = LCC.capture_ui_state(options)

Requirements​

LCC.capture_ui_state requires the ui_element module with ui_element._VERSION at 0.6.0 or newer. If the module cannot be loaded, has no valid version, is older than 0.6.0, or lacks UI-state capture support, the call asks the user to update XXTouch before using capture_ui_state and does not create a partial state object.

Parameters​

  • options.hit_test_spacing: optional positive integer; screen hit-test sampling spacing, default 40.
  • options.force_hit_test: optional boolean; force screen-sampling hit tests, default false.

Return Value​

Returns a UI-state object. It immediately captures the current PNG screenshot and raw text-element tree, then builds one .xxtuie archive. Saving and logging later reuse the exact cached bytes without recapturing.

local state = LCC.capture_ui_state({
    hit_test_spacing = 40,
    force_hit_test = false,
})

local info = state:status()
local ok, err = state:save_to_file(XXT_SCRIPTS_PATH .. "/scene.xxtuie")
if not ok then
    error(err)
end

LCC.log(1, "Scene", state)
state:destroy()

Object Methods​

state:status()​

Returns a new status table on every call, so changing it never changes internal state. It remains available after the object is destroyed.

  • status: complete, screenshot, elements, or unavailable.
  • captured_at / capturedAt: UTC time at which capture started.
  • screenshot.status: captured or unavailable, plus width and height; failures also include error.
  • elements.status: captured or unavailable, plus count; failures also include error.

state:save_to_file(path)​

Atomically writes the cached archive to the specified path, replacing an existing file. It returns true on success or nil, err on failure. The path and extension are used exactly as supplied; .xxtuie is recommended so file managers can detect it automatically. Saving is unavailable after destruction.

state:destroy()​

Releases the cached archive. It is idempotent. After destruction, status() still works, while saving and logging fail.

Partial Capture Failures​

After the version and capability checks pass, the screenshot and element tree are captured independently. If either runtime capture fails, the result is still a valid archive with exactly manifest.json, screenshot.png, and elements.json: an unavailable screenshot uses a transparent 1×1 PNG, an unavailable element tree uses an empty element array, and the manifest stores a short error. LCC.capture_ui_state() raises when its dependency is unsupported, parameters are invalid, the archive cannot be built, or the archive exceeds 20 MiB.

The original PNG is limited to 16 MiB, 16384 pixels per side, and 12 megapixels. Element JSON is limited to 4 MiB, 5000 nodes, and depth index 32. Exceeding an individual limit marks that item as unavailable.