PSPRecomp/docs/VCS_CLOUDWORKS_GAME_INTEGRATION.md

# CloudWorks: integração 1:1 com o estado do GTA VCS

## Estado atual

O shader usa os três perfis físicos, march adaptativo, sombras, extinção,
atmosfera e composição front-to-back do CloudWorks/ProperShaders. A câmera vem
do estado autoritativo do jogo (`TheCamera + 0x9B0`) e o passe é inserido no
world target depois dos opacos e antes do primeiro grupo equivalente a
`FadingEntities`.

Os valores que o ProperShaders de San Andreas obtém do timecycle e de
`CWeather` ainda são placeholders em `ProperShaders.ini`. Isso é intencional:
ligar um endereço não confirmado ao shader produz mudanças de clima erradas ou
leituras inválidas e não constitui uma integração 1:1.

## Fontes que precisam ser identificadas no guest

Para substituir cada placeholder, localizar no ELF do VCS e validar em runtime:

| Campo do INI | Fonte conceitual do ProperShaders/SA | Evidência necessária no VCS |
|---|---|---|
| `CoverageLow/Mid/High` | grupos de clima atual/anterior e interpolação | observar transições sunny/cloudy/rain/fog e reconstruir os três pesos |
| `SunDirection*` | direção real do sol ou lua | vetor unitário acompanhando hora; confirmar eixos do mundo do VCS |
| `DayProgression` | componente vertical da direção solar | faixa e pontos de troca sol/lua confirmados durante um ciclo completo |
| `SunColor*` | cor da corona/timecycle, modulada pelo clima | identificar RGB linear versus 0–255 e interpolação old/new weather |
| `CloudBaseColor*` | cor da base das nuvens do timecycle | separar da cor do céu/horizonte e validar dia, pôr do sol, noite e chuva |
| `AtmosphereDensity` | intensidade de chuva | localizar intensidade interpolada, não apenas o ID do clima |
| `Mist` | chuva, neblina e cloudiness combinadas | validar as três intensidades continuamente interpoladas |
| `FogColor*` | cor inferior do céu/horizonte | confirmar espaço de cor e ordem RGB |
| `FogStart` | plano inicial de fog da câmera | comparar com comandos GE `FOG1/FOG2` e o far clip do frame |
| `Speed` | tempo em segundos e vento | relógio monotônico do jogo + intensidade de vento interpolada |
| `RandomSeed` | seed de início/save, limitado e convertido em fase | escolher estatística estável e aplicar wrap em `2*pi` |

O relógio já tem uma pista confirmada: `gp + 0x1DE0` (hora) e
`gp + 0x1DE1` (minuto), usados por Project2DFX. Isso ajuda a localizar as
rotinas adjacentes de `CClock`, mas não substitui a direção solar contínua.

## Método de investigação

1. Encontrar referências às variáveis de hora conhecidas no AOT/disassembly e
   seguir os consumidores que atualizam iluminação, céu e clima.
2. Instrumentar somente candidatos concretos, no máximo uma vez por frame, em
   um log contendo hora, weather IDs/interpolação, vetores e cores.
3. Capturar uma rota reproduzível cobrindo meio-dia, pôr do sol, noite,
   amanhecer, chuva e neblina. Confirmar continuidade e faixa de cada campo.
4. Criar um `VcsCloudWeatherState` lido do `GuestMemory` no mesmo ponto em que a
   câmera autoritativa é capturada. Nunca ler guest memory no pixel/draw hot path.
5. Manter fallback por campo: valor guest validado quando finito e dentro da
   faixa; caso contrário, placeholder do INI e aviso limitado no log.
6. Comparar screenshots pareadas contra o ProperShaders com as mesmas entradas
   numéricas antes de ajustar qualquer constante artística.

## Renderização e ordem

O PSP não expõe um marcador chamado `RenderFadingEntities`. A fronteira atual é
inferida pelo estado GE: após geometria do world target com depth test+write,
sem blend/alpha test, o primeiro draw com blend, alpha test ou depth sem write é
tratado como o início dos objetos transparentes. O passe de nuvens é gravado
imediatamente antes desse draw, com depth `EQUAL` ao clear reverso (zero), para
preencher somente céu e permitir que árvores/grades/partículas sejam desenhadas
por cima.

Essa heurística deve ser validada em interiores, água, chuva, reflexos e efeitos
de missão. Se houver falsos limites, o passo seguinte é identificar o PC guest
da função que emite o primeiro draw de fading e transportar um marcador de fase
para o backend GE.

## Critérios para considerar a integração concluída

- Nenhum parâmetro visual de clima permanece obrigatório no INI.
- Transições old/new weather são contínuas e não saltam entre frames.
- Sol, lua, fog e base das nuvens acompanham o timecycle em um ciclo de 24 h.
- Nuvens ficam fixas no mundo durante rotação e translação da câmera.
- Opacos ocluem as nuvens; fading/folhagem/partículas são compostos por cima.
- Interior e cutscene não reutilizam uma câmera/target auxiliar.
- Um toggle desativa o recurso sem alterar a imagem original.
- Capturas A/B com entradas iguais reproduzem o ProperShaders sem ajustes
  específicos feitos apenas para uma screenshot.