flutter3d_sim_mcp library

Two servers over one level and one renderer.

ai-00: a level an agent can play blind, over MCP — of whatever game a host hands the session as a HeadlessGame (SimMcpServer).

par-02: why a frame of it is wrong, without guessing — a headless frame in one of the renderer's own debug views, the raw unclamped value of one pixel, what the frame graph actually ran, and a scan for the first pixel that is not finite (DiagnosticMcpServer). Genre-agnostic: its EntityRegistry is a parameter nothing here fills in.

They were two packages with the same dependency closure, and a picture from the first was already the second's lit frame.

See pubspec.yaml for why these servers need Flutter — unlike flutter3d_editor_mcp and flutter3d_model_mcp — and speak their protocol over a socket rather than over literal stdio.

Classes

AlivePredicate
who is up when alive is true, and down when it is false.
DiagnosticFrame
One rendered frame, read back two ways: png is what a person or a model looks at, raw is what a diagnostic actually computes from — the same texture, before CpuDevice.readPixels's clamp to 8 bits throws away everything a depth or a NaN needed.
DiagnosticMcpServer
A rendered frame, offered to an agent as a table of tools — par-02.
DiagnosticRenderer
A level's own scene, drawn with no GPU, in whichever of DiagnosticView's four readings a caller asks for — par-02.
HealthPredicate
who's health is under below and at least atLeast, whichever of the two are given.
InsidePredicate
who stands inside the box from min to max, edges included.
NearPredicate
who stands within within metres of point.
Playtest
ai-01: many independent playthroughs of the same level of game, run in parallel isolates, driven by nothing but a seeded random policy — where a level swallows a player who never learns it, rather than where one who is choosing well happens to go.
PlaytestRun
One playthrough, played to an ending rather than to a snapshot — Playtest.run asks for many of these at once.
ReadingPredicate
One claim about one row of a reading: the player, or an actor by name.
SimMcpServer
A level of whatever game SimSession.game is, offered to an agent as a table of tools — ai-00.
SimRenderer
A picture of the room, drawn with no GPU — SimSession.frame's other half.
SimSession
One level of game, open for the life of the process, an agent can walk through blind.

Enums

DiagnosticView
Which of the renderer's own debug outputs a frame is asked for — the four ways RenderSettings already knows how to answer "why is the frame wrong", and the whole of what this diagnostic adds on top: reading them back as raw floats rather than as a picture nobody who is not looking at it can act on.
PlaytestOutcome
How one playthrough ended.

Constants

renderMcpVersion → const String
The version this server tells a client it is: the pubspec's.
simMcpVersion → const String
The version this server tells a client it is: the pubspec's.

Properties

diagnosticTools → List<DiagnosticTool>
The five verbs par-02 asks for.
no setter

Functions

decodeOctahedralNormal(double r, double g) → Vector3
Decodes DiagnosticView.normals's R and G channels back into a unit vector — the exact inverse of EncodeOctahedral in packages/flutter3d_shaders/shaders/lib/color.glsl, transcribed rather than re-derived so the two cannot silently disagree about which fold a negative Z takes.
describePass(DiagnosticView view) → String
Which pass a channel not finite, or a pixel darker than it should be, is actually attributable to — stated once per DiagnosticView rather than guessed per call, since it does not depend on the pixel.
simToolsFor(HeadlessGame game) → List<SimTool>
The six verbs ai-00 asks for, with step offering game's own buttons as its own arguments — fire for the shooter, whatever another game names — and the two that turn a claim about a run into a file that proves it.

Typedefs

DiagnosticTool = OfferedTool<DiagnosticSession, PictureAnswer>
One tool: what an agent is offered, and what calling it does — see flutter3d_mcp_kit's OfferedTool.
PictureAnswer = ({bool did, Uint8List? png, String says})
An Answer with the picture a drawing tool hands back beside the sentence, null for every tool that draws nothing.
SimTool = OfferedTool<SimSession, PictureAnswer>
One tool: what an agent is offered, and what calling it does — see flutter3d_mcp_kit's OfferedTool.

Exceptions / Errors

ReadingPredicateException
Thrown when a claim cannot be read, or names somebody the reading does not have.