Skip to content

refactor: split StructuralAnalysisSystem into connectivity + stress systems #1

Description

@ThreeIce

What to build

Split \JerikoStructuralAnalysisSystem\ into two independent systems to align with the logical module boundary between connectivity/state determination and stress computation.

System A: Connectivity Analysis (belongs to Connection Graph module)

  • Phase 1: Map dirty elements to dirty islands
  • Phase 2: Multi-source BFS from boundary Anchors, assign Layers, determine reachable/unreachable
  • Phase 3: Dynamic cleanup (transition unreachable elements)
  • State transitions (Static/Dynamic) and state change events

System B: Stress Computation (belongs to Structural Stress module)

  • Only runs when topology changes occur — not every frame
  • Scoped to affected islands only (minimize computation surface)
  • Collect dirty island members, read Layer from JerikoElement component
  • Top-down weight accumulation (highest layer to lowest)
  • Stress computation: max(0, accumulatedLoad - ownMass) * coefficient
  • Write AccumulatedLoad and Stress to JerikoStructuralStress component
  • Specific triggering/scheduling mechanism TBD at implementation time

Dependency: A triggers B

System A and System B are decoupled. When System A completes topology rebuild for dirty islands, it signals (via event or dirty flag) that stress recomputation is needed for those islands. System B reacts to this signal and only recomputes stress for the affected islands. If no topology changes occur in a given frame, System B does not run. Cached stress values persist between frames for unaffected islands.

Rationale

Currently the single IslandAnalysisJob mixes graph-topology operations (BFS, reachability) with mechanical analysis (weight flow, stress). Splitting them:

  • Aligns code structure with logical module boundaries
  • Makes each system independently testable
  • Enables stress computation to be skipped entirely on frames with no topology changes
  • Minimal performance impact: BFS (the expensive part) runs once in System A; System B only does linear iteration + arithmetic on dirty islands

Acceptance criteria

  • New system (e.g. JerikoStressComputationSystem) handles weight accumulation and stress calculation
  • JerikoStructuralAnalysisSystem no longer contains weight/stress logic
  • System B only executes when System A signals topology changes (not every frame)
  • System B is scoped to affected islands only — unaffected islands retain cached values
  • New system reads Layer from JerikoElement component (written by System A)
  • All existing structural stress integration tests pass without modification
  • No measurable performance regression (profile with 10-building stress test scene)

Blocked by

None - can start immediately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions