Ymir/docs/planning/prds/modules/simulation.md

Contexto: Orquestração

Coordena a execução da simulação e a comunicação entre módulos.

---

Simulation

Controla o avanço do tempo e garante que todos os módulos sejam executados na ordem correta.

Responsabilidades

• Iniciar, encerrar, pausar e retomar uma simulação
• Controlar velocidade (real-time 1×, acelerado N×)
• Executar ciclos de atualização (ticks) em ordem determinística
• Em real-time: sincronizar loop com tempo de relógio
• Em fast-time: loop roda sem sincronização (o mais rápido possível)

Ciclo de tick

A cada tick, a Simulation executa na ordem:

1. [Environment]    atualiza condições ambientais (vento, corrente, maré)
2. [Terrain]        aplica modificações de terreno pendentes
3. [Vessel]         updateControl(time, dt) — atualiza demands de leme/RPM se modo manobra
4. [Vessel]         updateStates(time, dt)  — transforma corrente/vento p/ frame do navio,
                                              atualiza atuadores (1ª ordem / rate limiter),
                                              calcula SOG/COG/speedToWater, EMA de posição
5. [Hydrodynamics]  calcula forças hidrodinâmicas (damping, current, squat, thrust, rudder, tug)
6. [WaveForces]     calcula forças de onda (excitação + drift + RAO)
7. [InertialForces] acoplamento Coriolis/giroscópico
8. [RestoringForces] restauração hidrostática
9. [Mooring]        forças de cabos de amarração
10. [Anchoring]     forças de fundeio
11. [Physics/CVODE] soma todas as forças → integra movimento → atualiza World
12. [Events]        publica eventos do tick para assinantes internos e externos

Integrador — CVODE

• dt passado à Simulation é o intervalo de output (ex: 0.05–0.1 s)
• CVODE usa sub-passos adaptativos internamente — pode usar passos menores que dt para manter tolerância
• Múltiplos corpos: cada um tem sua própria instância CVODE (estado e solver independentes)

Múltiplas simulações

• Cada simulação é um par Simulation + World independente
• No apps/server: isolamento por thread (1–2 simulações real-time)
• No apps/fast-time: isolamento por processo (N simulações batch em paralelo)

---

Events

Sistema de pub/sub para comunicação entre módulos internos e clientes externos.

Responsabilidades

• Receber eventos publicados por qualquer módulo durante um tick
• Entregar a assinantes internos (outros módulos, sem latência)
• Propagar para clientes externos via Server (Manager, Viewer) — apenas em real-time

Eventos publicados

Evento	Publicado por	Descrição
collision	Physics	Dois corpos em contato
entity_created	World	Nova entidade adicionada
entity_removed	World	Entidade removida
mooring_ruptured	Mooring	Cabo de amarração rompeu
anchor_holding	Anchoring	Âncora unhada no fundo
anchor_dragging	Anchoring	Âncora garreando
environment_changed	Environment	Condição ambiental alterada
terrain_changed	Terrain	Batimetria ou estrutura modificada
simulation_started	Simulation	Simulação iniciada
simulation_paused	Simulation	Simulação pausada
simulation_ended	Simulation	Simulação encerrada
vessel_state_changed	VesselState	Luzes/shapes/estado operacional mudaram

Notas

• Fast-time: eventos propagados apenas internamente, não para clientes externos
• Histórico de eventos persistido por Persistence (junto com o histórico de steps)
• Viewer e Manager subscrevem todos os eventos da simulação em real-time