flutter3d_editor_core library

A level editor with the editor taken out: the document, what nudging it means, what a pointer hits, what a palette offers, and what a template turns into.

Plain Dart, and that is the whole of why this package exists. The document layer sat in apps/flutter3d_editor/lib/src for as long as the editor was the only program that wanted it. The moment anything else did — a command-line linter for a level, a tool an agent speaks to, a service that checks an uploaded level before a player ever loads it — it had to depend on an application, and no package depends on an application in tool/structure.dart says no. It says no because pub cannot express such a dependency at all: an application is not published, so the dependency exists only inside this checkout and only on a machine that has it.

What it does not do

It does not draw. Handle is a box with a colour and a size, not a mesh and not a widget; turning a list of handles into something on a screen is flutter3d_app's and the editor's, and nothing here knows that anything does.

It does not read a disk. Editing parses text and writes text back, scaffold returns a project as a map of bytes, and neither opens a file. The half with dart:io in it — pick a path, read it, write it down again — stayed in the application, because that half is where a crash loses somebody's work and where a platform gets an opinion.

It knows no genre. A document says monster or coin or checkpoint and this package vouches for none of it: vocabularyOf makes every type the level happens to name a flutter3d_sim OpenKind, so an editor built on it opens a game it has never heard of. The rule is held by the engine names no genre in the scan, and Looks is how a game gets to say what its own words look like without a line of code here learning them.

The boundary is checked rather than described: the simulation names no Flutter in tool/structure.dart reads a list of plain Dart packages, this one among them, and fails on the first import that would put a Flutter SDK in front of a program that only wants to open a level. The rule keeps the name it was published under, from the day the simulation was the only package on that list.

A second document lives here besides the level: .fmat. materialWith is the gate flutter3d_editor's material panel used to keep to itself — it could move only once MaterialDocument left flutter3d for flutter3d_formats, itself a plain Dart package, so this one could depend on it without a Flutter SDK arriving behind it. The second editor a .fmat field ever gets edited from does not have to write the gate again.

Classes

ActiveBinding: One edu_step's claim on an entity's property, per doc/edu-00-interactive-format.md §9: target names it, source and path say where the value comes from.
AddBrush: Puts a new brush down and selects it.
AddedAssetEntry: An asset-browser entry an editor has, by the name it is published under.
AddedImporter: An importer an editor has, by the name it is published under.
AddLevelLight: Puts a new light down and selects it.
ApplyOverrides: Writes the selected instance's overrides into its prefab — all of them, or those of the entity at path — so every instance gets them.
AssetBrowserEntry: A kind of file the asset browser lists, and what dropping one into the level does.
AssetPlacement: Where a file from the asset browser was dropped.
Brighten: Makes the selected light stronger or weaker, by a factor.
CreatePrefab: Turns the selected entities into a prefab called prefab, and puts one instance of it where they were — see Editing.createPrefab.
Delete: Removes whatever is selected — all of it, when several things are.
DocumentCommand: One thing somebody can do to a document, as a value rather than as a call.
DocumentText: The text a generated level document is written as.
DrawnMark: A GizmoMark where an editor drew it: the gizmo that drew it, by its published name, and the thing of the level it marks.
Duplicate: Copies whatever is selected, a step to the side, and selects the copy.
Editing: A level document, open and being changed.
EditorCommand: One of the editor's own commands — the ones editorCommandNames lists.
EditorComponent: A component: a named group of fields an inspector shows under one heading, and offers, at their defaults, where they are not set.
EditorGizmo: A gizmo a plugin draws: marks over the things it appliesTo, and the command a drag of one of their handles is.
EditorHints: The hints an editor's inspectors are built from: the slot a plugin finds with host.maybeRegistry<EditorHintRegistry>(), filled by EditorPieces, which brings one along as a companion.
EditorHistory: Everything that has been done to a document, and the way back.
EditorImporter: Brings a kind of file into a project: reads it, writes what the project keeps, and says what to do to the level.
EditorPieces: The EditorRegistry an editor fills: commands, inspector components and palette entries that plugins bring.
EditorRegistry: Editor commands, inspector components and palette entries: the slot EditorPieces fills, host.registry<EditorPieces>().
EditorSectionContents: What an editor: section held, read.
ExperimentEdit: One thing somebody can do to an experiment document, as a value.
ExperimentEditing: An experiment document open for editing: the document now, the edits that made it, and the documents to go back and forward to.
GeneratorSource: What a generator may read, and which of a directory's files exist.
GizmoContext: What a gizmo is asked about: one thing of the level, where it is, and whether it is selected.
GizmoDrag: A handle of a GizmoMark dragged from one point to another.
GizmoMark: One thing a gizmo draws: a shape in the world, in metres, and the name of the handle it is, when it can be dragged.
GizmoShape: The shape a GizmoMark is drawn as.
Handle: Something in the document that can be pointed at and moved.
ImportRequest: A file to import, and where it is going.
ImportResult: What an import produced: files to write into the project, commands to run on the level, and what to tell the person.
LightingState: One set of lights the level is also seen under, besides its own — the sun at noon, the sun at dusk, nothing at all at night.
LightOptimizer: Fewer lights that light a level the way its author lit it.
LightPlan: What LightOptimizer.optimize found: the lights before and after, what it did to get there, and the numbers that say whether to take it.
LightShading: A level drawn by the software rasteriser under any set of lights, in linear light: the renderer the light optimizer asks what a light does.
ListedPiece: One thing in a level document, named the way a selection names it.
Look: What one type looks like.
Looks: What a game's own words look like, told to the editor by the game.
MoveSelectionBy: Moves whatever is selected, by a vector, onto the grid.
MoveStep: The step step moved to position to of the scenario, from 0.
OutlineEntry: One row of an outliner: a thing in the level, and what to call it.
OutlineGroup: A heading in an outliner and the rows under it.
PaletteEntry: One row a plugin adds to the palette: an entity type to place, and what a placed one starts with.
Part: One shape in a silhouette.
Picking: A ray, and what it hits.
Piece: What a level is made of, from an editor's side.
Place: Puts one of what a palette row offers where it was dropped.
Placeable: One row of the palette.
PlacePrefab: Puts an instance of prefab down and selects it — see Editing.placePrefab.
PluginCommand: A command a plugin brings: one thing somebody can do to a document that the editor itself does not know.
PluginCommandInfo: One command a plugin added, as a tool server offers it.
RemoveExpectation: The step step no longer expecting a reading of probe.
RemoveParameter: The parameter id taken out; refused while a step still sets it.
RemoveProbe: The probe id taken out; refused while a step still expects it.
RemoveStep: The step step taken out of the scenario.
RemoveSubstance: The substance id taken out.
Resize: Grows or shrinks the selected brush about its own centre.
RevertOverrides: Drops the selected instance's overrides — all, those at path, or the one key there — so it shows its prefab again.
SetExpectation: What the probe probe should read when the step step ends, in place of what it expected before: value within tolerance, each a quantity as the file writes one.
SetExperimentField: One of the document's own words: its name, title, level (the level file, relative to the document) or profile. Null takes out what may be left out (title, profile).
SetField: Writes one field of the selected thing, or removes it when value is null.
SetLights: Puts a whole set of lights in place of the level's own.
SetOverride: Makes the selected instance's key of the entity at path say value, in that instance only — null takes the key away there.
SetParameter: A parameter, added or given a new value and bounds: each a quantity as the file writes one, {"value": 1, "unit": "m"}, or as text, "1 m".
SetPrefabField: Writes key of the entity at path in prefab's template, or takes it away when value is null: the edit every instance sees.
SetProbe: A probe, added or replaced by its id: the probe as the file writes it, with on for the level entity carrying it.
SetStep: A step of the scenario as the file writes it, in place of the one of its name, or added: at at when given, at the end otherwise.
SetSubstance: A substance the experiment uses, by catalog id, added or given a new role.
Template: A template, as its manifest describes it.
Turn: Turns the selected entity about the vertical.
UnpackPrefab: Breaks the selected instance's link to its prefab, one level down — see Editing.unpackPrefab.

Constants

builtInAssetEntries → const List<AddedAssetEntry>: The kinds of file the editor lists without a plugin, by name. A plugin's entry is asked first, so a plugin may claim a suffix listed here.
builtInComponents → const List<EditorComponent>: The editor's own components, in the order an inspector shows them, each piece's last one taking every key no section names.
editorCommandNames → const List<String>: Every command name, in the order a list of tools should offer them.
editorSection → const DataSection: The editor: section of a data plugin: the hints its components, entity kinds and lit models are edited with, as ComponentHints.toJson, EntityKindHints.toJson and MaterialHints.toJson write them.
experimentEditNames → const List<String>: Every edit's name, in the order a list of tools offers them.
gizmoSize → const double: How big the mark for something with no geometry is, in metres.
lightViewEyeHeight → const double: How high above the feet a player's eye is, in metres, when a view is taken from where somebody stood.
looksFile → const String: Where a game keeps the file, if it keeps one.
paletteLight → const String: The word a palette uses for a light, which is not an entity type and not a material.
projectPluginsDirectory → const String: Where a project keeps the data plugins its editor installs, relative to the project's root: beside its other assets, so the game ships the same files the editor read.

Functions

atLeast(LinearColor color, double floor) → LinearColor: color, brightened up to floor if it is dimmer than that.
bindingsInLevel(Level level) → Map<String, ActiveBinding>: Every binding any edu_step in level declares, keyed by its own target — сущность.путь-свойства, per edu-00 §9.
defaultLightViews(Level level, {double eyeHeight = lightViewEyeHeight}) → List<LightView>: Views for a level nobody has played yet: from every player spawn, four headings a quarter turn apart; with no spawn, from the middle of the level's brushes. Empty for a level with no brushes and no spawn.
freshName(Level level, String prefix) → String: A name for a new edu_step/edu_annotation/edu_clip_plane that no entity in level already carries — prefix-1, prefix-2, ... — because Editing.place copies the last entity of a type, name included, and two steps sharing one name is two entries in edu_sequence.steps that resolve to the same step.
handlesOf(Level level, {Looks looks = Looks.none}) → List<Handle>: Every handle in level, brushes included.
indexOfNamed(Level level, String name) → int?: edu-01's own arithmetic, kept out of any widget for the same reason bindingsInLevel and HeatmapLayout (ai-02) were: a merge into a JSON map or a reorder of a name list is cheaper to prove directly than through a WidgetTester drag, which only shows that painting and hit-testing agree with each other, not that either produces the right document.
inspectorComponents(Piece piece, {String? type, EditorPieces? pieces}) → List<EditorComponent>: The components an inspector shows for a piece of entity type type, in order: the editor's own but the last, then the ones pieces adds that belong there, then the editor's last, which takes every key none names.
inspectorSections(Piece piece, Iterable<String> keys, {String? type, EditorPieces? pieces}) → List<(String, List<String>)>: keys sorted into the inspectorComponents of piece: each section's title with the keys it holds, in order, and sections left empty dropped.
markUnder(List<DrawnMark> marks, Vector3 from, Vector3 along) → DrawnMark?: Which mark with a handle from pointing along hits first, or null.
materialDocumentFields(MaterialDocument document) → Map<String, Object?>: The fields of a .fmat, the way a panel built from it should show them.
materialDocumentHint(MaterialDocument document, String key, {EditorPieces? pieces}) → MaterialHint?: The hint for one field of a .fmat.
materialHintOf(FieldHint hint) → MaterialHint?: hint as the material panel's control, or null for a field it shows as plain text: a number without both ends, a toggle, a vector.
materialWith(MaterialDocument document, String key, Object? value, {MaterialHint? hint}) → MaterialDocument?: document with one field changed, or null when the change would produce a .fmat this engine's own reader does not take as written.
mergedOffsets(EntityDef step, String nodePath, Vector3 delta) → Map<String, Object?>: step's own offsets map, with nodePath set to delta — the value a caller hands SetField('offsets', ...) after a drag on a named node.
movedStep(List<String> steps, int from, int to) → List<String>: steps with the name at from moved to sit at to — the value a caller hands SetField('steps', ...) on the edu_sequence after dragging a row in a step list up or down.
outlineOf(Level level, {String filter = ''}) → List<OutlineGroup>: The level as a tree: its brushes, its lights, and its entities by type.
packageName(String typed) → String: The name a directory and a pub package can both have.
paletteOf(Level level, {Iterable<String> declared = const <String>[], EditorPieces? pieces}) → List<Placeable>: What can be put into a level, in the order a palette lists it.
piecesOf(Level level) → List<ListedPiece>: Everything level holds, flat, in the order the document writes its lists.
prefabListing(Level level) → String: The level's prefabs, one block each: the id, then one line per entity of its template with the path an override addresses it by — what an agent needs before it can write setOverride or setPrefabField.
projectAt(String levelPath) → ({String level, String root}): Where a project's directory is, given the level path somebody asked for.
projectPluginPaths(Iterable<String> files) → List<String>: The .f3dplugin documents among files, paths relative to a project's root, that the editor installs: those under projectPluginsDirectory, in sorted order so two machines install them alike.
pubspecFor(String name) → String: The pubspec.yaml a scaffolded project starts with.
readmeFor(String name, Template template) → String: The README.md a scaffolded project starts with.
roundNumber(num value, int digits) → num: value to digits places the way a document's own numbers are, keeping an int an int.
scaffold({required Template template, required String project, required Map<String, Uint8List> sources}) → Map<String, Uint8List>: Lays a new project out: every file, as bytes, against the path it goes to.
tintFor(String type) → LinearColor: A colour for an entity type.
viewsAlong(List<GhostFrame> poses, {int count = 8, int around = 1, double eyeHeight = lightViewEyeHeight}) → List<LightView>: Views along a path somebody walked: count of its poses, evenly spaced in time, each an eye eyeHeight above the pose looking the way it faced.
vocabularyOf(Level level) → EntityRegistry: A registry made of whatever level already names, each type an OpenKind.

Typedefs

CommandReader = PluginCommand? Function(Map<String, Object?> arguments): Reads a plugin command back from a call's arguments — everything but the command key — or answers null when they are not the shape it needs.
LevelGenerator = Map<String, String> Function(GeneratorSource source): A program that writes documents: the files it owns, by path, as text.
LightView = ({Vector3 at, Vector3 from}): Where the light optimizer looks at a level from: the eye, and the point it looks at.
Picked = ({int index, Piece kind}): One selected thing: which of the level's three lists, and which one in it.

Exceptions / Errors

GeneratorException: A generator refusing to write a document a player could not use.

flutter3d_editor_core library

What it does not do

Classes

Constants

Functions

Typedefs

Exceptions / Errors

flutter3d_editor_core package

flutter3d_editor_core library