Skip to main content

flutter3d_lints 1.0.0-rc.1 copy "flutter3d_lints: ^1.0.0-rc.1" to clipboard
flutter3d_lints: ^1.0.0-rc.1 copied to clipboard

Analyzer rules for code inside a flutter3d fixed step: no wall clock, no unseeded Random, no dart:math transcendental where Portable gives one answer everywhere.

flutter3d_lints #

Analyzer rules for code that runs inside a flutter3d fixed step. A plugin's simulation code is held to what the engine's own is: no wall clock, no dice the machine seeds, no transcendental whose answer is the platform's libm.

A replay is the same run only while every step computes the same thing from the same state, on every machine. A server that verifies a submitted run replays it through the same simulation, so one DateTime.now() in a plugin's step is a run the server rejects months later. These rules say so in the editor, the day the line is written.

The rules #

Rule Reports Instead
step_reads_no_clock DateTime.now(), Stopwatch the step count and the step's dt from the LoopContext
step_takes_seeded_random Random() with no seed, Random.secure() a GameRandom the step was handed, or Random(seed)
step_uses_portable_math sin, cos, tan, asin, acos, atan, atan2, exp, log, pow from dart:math Portable.sin and the rest, from flutter3d_sim
step_prefixes_dart_math import 'dart:math'; with no prefix import 'dart:math' as math;

sqrt is allowed: IEEE 754 requires a correctly rounded square root, so every platform gives the one right answer.

With a resolver the rules ask what a name is, not how it is spelled: m.sin(x) under import 'dart:math' as m; is reported, and a class of your own called Random is not. A comment or a string that names a forbidden call is not a call and is not reported.

Enabling it #

The rules ship as an analysis server plugin (Dart 3.10 and later). List the package under the top-level plugins: section of the analysis_options.yaml at the root of your package or workspace:

plugins:
  flutter3d_lints: ^1.0.0-rc.1

plugins: is a section of its own, not a key under analyzer:, and it is read only from the root options file. Restart the analysis server after changing it. The rules are registered as warnings, so listing the plugin turns all four on; to turn one off:

plugins:
  flutter3d_lints:
    version: ^1.0.0-rc.1
    diagnostics:
      step_prefixes_dart_math: false

They show in the editor and in dart analyze and flutter analyze.

Code that is not a step #

The rules are for code a fixed step runs. A plugin package usually also has code that runs once a frame: a camera, a particle's drift, a sound's pitch. That code may read the frame's clock and call dart:math, because nothing replays it. Plugins cannot be scoped from a nested options file, so say it in the file:

// ignore_for_file: flutter3d_lints/step_uses_portable_math

or on the one line:

final watch = Stopwatch()..start(); // ignore: flutter3d_lints/step_reads_no_clock

A file-wide ignore is a sentence about the file. Write beside it why the file is not a step, as this repository's own exemption tables do for theirs.

Migrating from 0.8 #

The plugin also reports code written against flutter3d 0.8 that 1.0 changed, from the migration table in flutter3d_build:

Diagnostic Reports Fix
flutter3d_migrate a deprecated capability getter on a GraphicsDevice; implements X where 1.0 made X a base mixin class; named arguments that moved into an options object; a switch over a type that stopped being an enum; .$1 of a record that became a class; a null check beside a call that throws now the quick fix rewrites it, with a TODO where the rewrite needs a decision
flutter3d_migrate_by_hand a use a person has to change, such as GameLoop the message links the guide's line for it
flutter3d_migrate_by_hand the import of a package whose names the file uses and 1.0 keeps to itself one diagnostic per import, naming them all

dart fix does not apply a plugin's fixes in bulk. To apply them all across a project:

dart pub global run flutter3d_lints:migrate [--dry-run] path/to/project

It also puts a // TODO(flutter3d-1.0): above each use left for a person. Where 1.0 exports a new name that your project already declares, it hides the new one on the flutter3d import. dart run flutter3d_build:migrate runs it as one step of the whole migration. The guide is at https://flutter3d.pleion.dev/reference/migrating-to-1.0/.

For tooling of your own #

package:flutter3d_lints/flutter3d_lints.dart exports scanSimulationCode, which takes a parsed or resolved CompilationUnit and returns the findings, and the rules' names in SimulationRules. The rules as the analysis server takes them are this package's own: they extend a class of analysis_server_plugin, which is at 0.x, and the analyzer loads them through main.dart.

This repository #

The engine's own packages are held to the same rules by tool/structure.dart (rules 7 and 34, "a step reaches for no clock and no loose dice" and "a step asks no machine for an answer"), not by this plugin. The structure scan is the first step of CI and runs before pub get, so it reads text and needs no analyzer. test/mirrors_structure_test.dart reads the structure tool's source and fails when the two lists disagree.

0
likes
0
points
207
downloads

Publisher

unverified uploader

Weekly Downloads

Analyzer rules for code inside a flutter3d fixed step: no wall clock, no unseeded Random, no dart:math transcendental where Portable gives one answer everywhere.

Homepage
Repository (GitHub)
View/report issues

Topics

#game-development #lints #analyzer #determinism

License

unknown (license)

Dependencies

analysis_server_plugin, analyzer

More

Packages that depend on flutter3d_lints