saga_map library

Classes

CompleteLevelResult
Result object returned by CompleteLevelUseCase.execute.
CompleteLevelUseCase
Marks a level complete, unlocks the next level and rolls boss rewards.
DefaultSagaBiomeThemeResolver
Built-in biome resolver with light/dark palettes.
InMemoryInventoryRepository
In-memory InventoryRepository implementation for demos and tests.
InMemorySagaProgressRepository
In-memory SagaProgressRepository implementation for demos and tests.
InventoryItem
Immutable inventory item model returned from rewards flow.
InventoryRepository
Persistence contract for inventory items.
LevelData
Immutable map node model that describes one level on the path.
LevelGenerator
Contract for deterministic level generation implementations.
LevelProgress
Persistable progression snapshot for one level id.
LootTableEntry
Weighted loot entry used by reward roll logic.
MapChunkWidget
Renders one map chunk: biome background, connecting path, and interactive level nodes.
NoopSagaLogger
No-op logger for consumers that do not need log output.
PainterRendererAdapter
Renders a chunk's path and biome background as a CustomPainter.
ProceduralBiomeGenerator
Noise-based biome generator for map terrain prototyping.
ResolvedSagaLayout
Fully resolved responsive values for a concrete viewport.
SagaBiomeTheme
Color and stroke tokens for painting one biome.
SagaBiomeThemeResolver
Resolves SagaBiomeTheme from biome id.
SagaCharacter
A character standing on, or moving along, the map's path.
SagaCharacterController
Drives a character along the path.
SagaCharacterState
Everything a character builder is told about the current frame.
SagaChunkContext
Everything a decoration or header builder needs about one chunk.
SagaInfiniteMapController
Stateful controller that manages lazy loading map chunks.
SagaInfiniteMapView
Infinite-scrolling map powered by SagaInfiniteMapController.
SagaLateralBounds
Normalized 0..1 band the level path zig-zags within, on the lateral axis.
SagaLogger
Logger abstraction used by domain services.
SagaMapBackgroundConfig
Immutable configuration object for map backgrounds.
SagaMapBreakpoint
Numeric range bound to a breakpoint name.
SagaMapCameraController
Imperative handle for moving the map's viewport.
SagaMapConfig
Geometry parameters used by SagaMapLevelGenerator.
SagaMapCoordinates
Coordinate conversion helpers for map rendering.
SagaMapDecoration
A scenery item placed on a chunk - a tree, a house, a cloud.
SagaMapGate
A barrier on the path that a closed gate holds the character behind.
SagaMapLevelGenerator
Default implementation that generates deterministic zig-zag map paths.
SagaMapRenderContext
Everything a renderer needs to draw one chunk.
SagaMapRenderer<TOutput>
Turns a chunk's SagaMapRenderContext into some renderable output.
SagaMapResponsiveConfig
Complete responsive config used by SagaResponsiveResolver.
SagaMapScrollPhysics
Scroll physics that scale drag distance by a responsive sensitivity factor.
SagaMapValuePolicy
Per-breakpoint numeric policy used for scale and spacing knobs.
SagaMapZoomConfig
Bounds for user-driven pinch zoom.
SagaNodeInteractionHandler
Callback container used by map widgets for node interactions.
SagaNodeInteractionPolicy
Interaction gating policy for map node gestures.
SagaPathMetrics
Arc-length measurements over a path, so something can travel it at an even pace.
SagaPathPose
Where something sits on the path, and which way it is heading.
SagaPathSegment
One cubic Bézier piece of the rendered path.
SagaPinchGestureRecognizer
Scale recognizer that ignores single-finger gestures.
SagaPityRule
A bad-luck guarantee for boss rewards.
SagaPoint
2D point with normalized or pixel coordinates.
SagaProgress
Aggregate progression model for all known levels.
SagaProgressClamp
What SagaProgress.fromJson changed when it reconciled a stored unlock pointer with the records beside it.
SagaProgressRepository
Persistence contract for map progression state.
SagaResponsiveResolver
Resolves responsive map layout values from the viewport.
SagaSize
Width/height pair used by map layout calculations.
SagaSpriteAnimation
Plays a clip from a sprite sheet.
SagaSpriteClip
A run of frames played at a fixed rate.
SagaSpritePainter
Draws one sprite frame into the box it is given.
SagaSpriteSheet
TerrainCell
One sampled cell from generated terrain.
TerrainMapConfig
Input parameters for procedural terrain generation.
TerrainMapData
Full generated terrain payload with occupancy and biome layers.
WidgetRendererAdapter
Renders a chunk's levels as positioned, interactive widgets.

Enums

CompleteLevelOutcome
What CompleteLevelUseCase.execute did with the request.
InventoryRarity
Item rarity tiers used by loot tables and inventory UI.
LevelCompletionState
Completion status for one level.
SagaCharacterAnchor
Which part of the character's art sits on the path.
SagaCharacterFacing
Which way along the path the character is oriented.
SagaCharacterGait
How the character travels between nodes.
SagaCharacterMotion
What the character is doing, for a builder that swaps animations.
SagaMapBackgroundKind
Background source kind used by map chunk rendering.
SagaMapBackgroundOverflowBehavior
Strategy used when chunk count exceeds provided backgrounds.
SagaMapBreakpointName
Named responsive breakpoints used by map layout policies.
SagaMapPathAxis
Which screen axis the level path advances along.
SagaNodeInteractionState
Visual/interaction state used by node callbacks.
SagaSpriteLayout
How frames are arranged inside a sprite sheet image.
SagaSpriteLoop
How a clip behaves once it reaches its last frame.

Extensions

LootTableOdds on List<LootTableEntry>
Drop-rate maths over a loot table, so a host can show the odds it is actually rolling against rather than restating the weights by hand.
SagaProgressStars on SagaProgress
Provides total star counts and chunk evaluation without duplicate loops.

Constants

kBiomeIdDesert → const String
Desert biome identifier used by level and theme systems.
kBiomeIdForest → const String
Forest biome identifier used by level and theme systems.
kBiomeIdGlacier → const String
Glacier biome identifier used by level and theme systems.
kDefaultSagaMapSeed → const int
Default seed used when repository has no persisted value.
kMaxLevelStars → const int
Upper bound on a level's star score.
kMaxTerrainCellCount → const int
Largest total cell count ProceduralBiomeGenerator will accept.
kMaxTerrainDimension → const int
Largest side length ProceduralBiomeGenerator will accept.
kMvpLootTable → const List<LootTableEntry>
Default MVP boss-drop table.
kPuzzleVersion → const int
Puzzle generation revision identifier.
kSagaBiomeIds → const List<String>
Ordered biome ids used by deterministic generator cycling.
kSagaDefaultNodeSize → const double
Default logical size of a node before responsive scaling.
kSagaMapChunkSize → const int
Default section count generated per infinite-map chunk.
kSagaMapGeneratorVersion → const int
Generator algorithm revision identifier.
kSagaMinTouchTarget → const double
Smallest touch target a node is allowed to expose, per platform accessibility guidance.
kSagaPathNeighborCount → const int
How many levels beyond each end of a chunk the renderer needs in order to curve the path identically on both sides of a seam.

Functions

buildSagaPathSegments(List<SagaPoint> points, {required double curvature}) → List<SagaPathSegment>
Builds the path connecting points as a list of cubic pieces.
chunkFractionForLevel({required int levelIndexInChunk, required int levelsPerChunk, double edgeInsetFraction = 0.0}) → double
Computes the normalized chunk fraction (0.0 to 1.0) for a given level.
clampTravelThroughGates(Iterable<SagaMapGate> gates, double from, double to, {double stopMargin = 0.0001}) → double
Clamps a move from from to to so it stops at the first closed gate in the way.
debugResetUnknownBiomeWarnings() → void
Clears the "already warned" set. Test-only.
defaultSagaNodeSemanticsLabel(LevelData level, LevelProgress? progress) → String
Default English screen-reader label: level number plus its state. Shows id + 1.
describeDegenerateSheet({required SagaSpriteLayout layout, required int frameCount, required int? columns}) → String
Describes how to cut an image into equally sized frames.
getDominantBiomeId(List<LevelData> levels) → String
Returns the most frequent biome id in levels.
isBossLevel(int levelId) → bool
Whether levelId is a boss level.
puzzleSeedForLevel(int globalMapSeed, int levelId, int puzzleVersion) → int
Creates deterministic puzzle seed from map seed, level id and version.
puzzleSeedForLevelWithDefaultVersion(int globalMapSeed, int levelId) → int
Convenience overload that uses current kPuzzleVersion.
rollBossReward({required int levelId, required int globalSeed, List<LootTableEntry> table = kMvpLootTable, DateTime? now, int pityCounter = 0, SagaPityRule? pityRule}) → InventoryItem
Rolls a deterministic reward for boss levels.
stableHash(List<int> values) → int
Combines values into a stable 32-bit hash.
stableUnitValue(List<int> values) → double
Stable hash of values mapped to the [0, 1) range.

Typedefs

SagaBossRule = bool Function(int levelId)
Decides whether a level is a boss encounter.
SagaCameraScrollHandler = Future<void> Function(double pathPosition, {required double alignment, required Curve curve, required Duration duration})
Scrolls the map so pathPosition sits at alignment in the viewport.
SagaCharacterBuilder = Widget Function(BuildContext context, SagaCharacterState state)
Builds the character's visual.
SagaChunkLevelLoader = FutureOr<List<LevelData>> Function(int chunkIndex, int sectionsPerChunk)
Async chunk loader callback used by SagaInfiniteMapController.
SagaEpisodeHeaderBuilder = Widget? Function(BuildContext context, SagaChunkContext chunk)
Builds an episode banner or divider before a chunk in the scroll direction. Return null to leave the chunk bare.
SagaInfiniteNodeBuilder = Widget Function(BuildContext context, LevelData level, ResolvedSagaLayout layout)
Node builder signature used by SagaInfiniteMapView.
SagaLegacyEpisodeHeaderBuilder = Widget? Function(BuildContext context, int chunkIndex)
SagaMapBackgroundBuilder = Widget Function(BuildContext context, int? chunkIndex)
SagaMapBackgroundErrorBuilder = Widget Function(BuildContext context, int? chunkIndex, String assetPath, Object error)
Builds a background layer for one chunk.
SagaMapDecorationBuilder = List<SagaMapDecoration> Function(BuildContext context, SagaChunkContext chunk)
Produces the decorations for one chunk.
SagaMapLegacyDecorationBuilder = List<SagaMapDecoration> Function(BuildContext context, int chunkIndex)
SagaNodeBuilder = Widget Function(BuildContext context, LevelData level, ResolvedSagaLayout layout)
Builds the visual for one level node.
SagaNodeFocusChangeCallback = void Function(LevelData level, SagaNodeInteractionState state)
Focus-state callback signature for level nodes.
SagaNodeHoverCallback = void Function(LevelData level, bool isHovered)
Hover callback signature for level nodes.
SagaNodeLongPressCallback = void Function(LevelData level)
Long-press callback signature for level nodes.
SagaNodeProgressResolver = LevelProgress? Function(LevelData level)
Resolves persisted progress for a level, or null when untracked.
SagaNodeReachability = bool Function(LevelData level, LevelProgress? progress)
Decides whether a node can be reached at all, independently of the progress recorded for it.
SagaNodeSemanticsLabelBuilder = String Function(LevelData level, LevelProgress? progress)
Builds the screen-reader label for one level node.
SagaNodeTapCallback = void Function(LevelData level)
Tap callback signature for level nodes.

Exceptions / Errors

InvalidTerrainConfigException
SagaDomainException
Base exception type for recoverable saga-domain failures.