procgen.profile

What evaluating procgen graphs has cost, read from what was recorded as the work ran, so it answers for cooks that already happened and cooks nothing itself. Reach for it when an effect or a generator is slow, to find the node the time goes to.

With no arguments it answers the report of everything recorded: every graph with what its presents ran (the time the work ran, none of the frames it waited across) and waited, then one graph opened as it was written, each level listing its nodes costliest first, each reading everything that ran inside it, with the costliest opened in turn. Each node line says what of that was a first cook, cooked again or cache checks, and its dispatches, uploads and read-backs. (plan), (tick) and (present) hold what those phases spent outside every node. The verdicts name what was paid again and by which node, the graphs over the 1 ms frame bar, and the waits by site.

• graph opens the graph whose name contains this (default the costliest); at opens the node at the path a/b/c of the node ids the lines show; width is the children shown per level (default 6) and depth the levels opened (default 12).
• record = true records what every play costs from then on (procgen.play records its own play either way), record = false stops; the answer is { recording }.
• reset = true forgets every recorded cost.
• save = "<name>" keeps the recorded costs at /zero/source/tmp/profiles/<name>.json and answers { saved, graphs }; compare = "<name>" lists, after the verdicts, the nodes that got dearer or cheaper than in that run by more than 10% and 0.5 ms.
• invoke = "<graph name>" invokes that graph once, the way any caller evaluates it, and answers what that one invoke cost as { text }: each node by its own cost, whether it cooked and why or was kept, then the waits by site. What it cooks is kept for the next invoke: time (seconds, default 0) and params say what to invoke, dirty = true lets go of everything kept first, repeats invokes the same case that many times and reports the least, middle and most, advance = true makes each of those a frame after the one before, and dump names a VFS path every span is written to as JSON.

tools.use("procgen", "profile", { invoke = "scratch.Box" })
tools.use("procgen", "profile", { invoke = "scratch.Box", time = 1 / 30, dirty = true })
tools.use("procgen", "profile", { save = "before" })
tools.use("procgen", "profile", { compare = "before" })

Part of procgen.toolbox, called as tools.use("procgen", "profile", ...) (zero procgen profile in the engine shell). Returns { text, verdictText, treeText, comparisonText, verdicts, comparison, graphs, recording }.