QG flow programs

QG expresses ordered automation behavior: call Objects, evaluate conditions, wait, record state, and handle faults and recovery. The only current source format is .qg. Source and Flow are two views of the same program.

If this is your first QG task, complete QG flow, Object calls, and Debug before using this page as a reference.

When to use QG

QG is a good fit for:

• ordering equipment or business actions;
• conditions, branches, bounded waits, and timeouts;
• coordinating several Objects;
• behavior that runs when an App starts, updates, or stops;
• control logic that you need to observe with Debug breakpoints.

Do not use QG for:

• Page layout and button appearance;
• protocol handling, register parsing, or driver implementation;
• emergency stops, safety circuits, or certified safety functions;
• unmanaged third-party code, dynamic scripts, or unbounded background work.

Create and open a QG program

1. Right-click Scripts in Resources.
2. Select Create QG Program and use a clear, stable filename such as packaging-station.qg.
3. The editor creates the source under graphs/ and establishes its corresponding Object instance. Confirm its Object ID and name under Resources → Objects.
4. Write or review source in Source and switch to Flow when a structured view is useful.
5. Save, resolve live document diagnostics, and use Build when you need a complete result.

Start each QG file with a short JSDoc paragraph that explains the capability it provides to the App. Describe engineering purpose, such as “orchestrates packaging cycles and timeout recovery,” rather than implementation history or volatile parameters.

Source and Flow

• Source is the only source of truth and can be edited by people or AI.
• Flow is generated from current Source and presents functions, conditions, loops, and Object calls as a structured flow.
• An accepted Flow edit updates the same Source. There is no second wiring file, coordinate file, or draft to synchronize.
• Source and Flow use the same breakpoints. After source locations change, run Build Debug again before starting a new debug session.

If Flow cannot render, inspect Source and Problems first. Do not create an empty flow by deleting types or guessing method names while upstream QG or Object errors remain.

Program structure

A QG program normally contains three kinds of content:

Content	Purpose
Top-level state	Short-lived state shared within the current runtime instance; reset when the instance is reloaded
Ordinary functions	Local calculations and process steps used only by this QG program
export function	Methods that this QG Object exposes to Pages, other QG programs, or approved online tools

The only optional lifecycle functions are:

• Init(): void: runs once when the App starts;
• Update(): void: called periodically by the Runtime while running;
• Dispose(): void: runs during Stop or fault cleanup.

Do not create a second scan timer or permanent loop inside QG. Keep each Update bounded and give every external wait an explicit timeout and recovery path.

Use Object capabilities

QG calls bound Objects through objects.<reference>.<method>(...). Use this workflow:

1. Select Add Object reference in Flow, or choose the target instance in Object properties.
2. Select a capability from the current method list supplied by the editor.
3. Pass values in the displayed order, type, and unit.
4. Save and resolve Object or QG diagnostics.
5. After Build, verify real behavior in a simulator or approved equipment state.

Object methods must come from capabilities installed in the current App. Never infer method names, units, polarity, or permissives from an old project, screenshot, or similar device. AI should also inspect the current Object catalog first and open only the Provider interfaces it actually needs.

Common language rules

QG uses syntax that TypeScript tools can understand, but it is not a general JavaScript runtime.

What you need	Current syntax
Boolean	bool
Signed integers	i8, i16, i32, i64
Unsigned integers	u8, u16, u32, u64
Floating point	f32, f64
Text and no return value	string, void
Fixed record	A top-level TypeScript interface whose fields use exact scalar types
One-dimensional list	T[], with length, indexing, assignment, push, and for...of

Important limits:

• Do not use number, boolean, any, unknown, or null.
• Make numeric conversions explicit, such as u32(value).
• Do not use async, await, Promise, exceptions, classes, imports, or dynamic modules.
• Object calls complete in source order. Do not add asynchronous markers even when an underlying operation waits.
• Every loop needs a clear exit condition. QG does not add an automatic iteration limit to an infinite loop.

Treat editor diagnostics as authoritative. Do not bypass them with casts, suppression comments, or generated code.

Time, logging, and durable state

QG provides a small set of built-in capabilities:

• QG.clock.monotonicMilliseconds() reads monotonic time.
• QG.clock.delay(milliseconds) performs a cancellable wait.
• QG.log.debug/info/warn/error(...) writes runtime logs.
• QG.math, QG.bits, and QG.array support exact math, bit operations, and arrays.
• QG.saved.get/set stores scalars or fixed records that must survive runtime-instance replacement.

Durable state belongs to the current runtime target. It is not written back to the App workspace or moved automatically with Git. A successful QG.saved.set is not rolled back by a later fault. Plan an explicit migration or use a new name when changing a stored shape.

Example:

export function IncrementTotal(): u64 {
  let total: u64 = QG.saved.get("totalCycles", u64(0));
  total = total + u64(1);
  QG.saved.set("totalCycles", total);
  return total;
}

When a Page needs a durable value, call an exported QG Object method instead of owning another persistence implementation.

Debug a QG program

1. Save QG and related Object changes.
2. Add breakpoints to the intended statements in Source or Flow.
3. Confirm Stopped, then select Build Debug.
4. Select Debug. If no suitable Build exists, the editor asks whether to Build and continue; it proceeds only after confirmation.
5. Trigger the target method from a Page, another QG program, or an approved online entry.
6. At a breakpoint, inspect the current statement, arguments, state, Console, and equipment feedback, then select Continue.
7. Select Stop to end Debug and verify the equipment's cleaned-up state.

The current debugger provides breakpoints and Continue, but not source stepping or conditional breakpoints. Debug does not simulate devices, skip real outputs, or prove process safety.

Save, Build, and runtime boundaries

• Save updates project files only. Flow and live diagnostics also describe source only.
• Build uses files saved to disk and deploys the result to the selected runtime target.
• Preview never Builds or Deploys. It uses only the dedicated Previewing state, and its Object calls can have real side effects.
• Start and Debug execute the deployed version. When the editor offers Build, it waits for explicit user confirmation before building and continuing.
• QG and Objects are never replaced in a running instance. Use Stop → Save → Build → Start/Debug after a change.

Common problems

Flow is empty or a method is missing

Resolve upstream Source and Object errors first. Confirm that the reference points to the intended instance, then reopen Flow. Do not handwrite an interface or fill the gap with an old method name.

A Page cannot find a QG method

Confirm export function, save the QG file, verify the corresponding Object binding, and run Build again. Pages receive only methods in the current resolved Object model.

A breakpoint does not hit

Confirm that the current source has a matching Build Debug, the breakpoint is inside the executed method, and Debug uses the target bound to this editor.

Equipment still shows old behavior

Save does not replace the runtime instance. Stop, Build, and Start/Debug again, and verify the title bar's runtime target.

The App returns to Stopped after a fault

This is the unified cleanup behavior. Record the fault phase, message, triggering action, and Console output before repairing the cause. Do not hide an unexplained fault by repeatedly selecting Start.

Engineering and safety checks

Before connecting real equipment, confirm:

• Object identity, address, unit, polarity, and range;
• start permissives and the safe state after Stop;
• timeout, cancellation, and recovery for every wait;
• equipment behavior in Init, Dispose, and fault cleanup;
• whether retries can repeat an irreversible side effect;
• that emergency stops, guards, and hard limits are enforced by a separate, suitable safety system.

QG owns flow orchestration. It does not replace device drivers, backend authorization, or certified safety control.

Related pages

• QG flow, Object calls, and Debug tutorial
• Objects and device capabilities
• From Save to runtime
• Build and runtime acceptance