O que é e como funciona o White Castle
O White Castle é um motor de renderização de cena 3D de código aberto voltado principalmente para aplicações em tempo real. Ele nasceu como uma alternativa mais leve a engines maiores, focando em Pipeline gráfico simples com suporte a Vulkan e OpenGL. Se você está procurando algo entre um motor completo como Unreal ou Unity e um projeto puro com DirectX/Vulkan, o White Castle fica nessa zona intermediária. A estrutura do projeto é baseada em componentes ECS (Entity Component System), o que significa que a organização do código funciona de forma bastante diferente do paradigma tradicional de herança de classes. Entidades são apenas IDs inteiros, componentes são structs de dados puros, e sistemas processam esses dados em loops separados. Isso pode parecer excessivamente verboso no início, mas escala muito melhor quando o projeto cresce.
Instalação e setup inicial do the white castle
O repositório oficial fica no GitHub sob o nome "whitecastle-engine". O build requer CMake 3.20+ e um compilador C++17 compatível. No Linux, as dependências principais são GLAD para a camada de inicialização do contexto gráfico, GLFW para janela e entrada, e stb_image para carregamento básico de texturas. No Windows, o mesmo vale, mas você também vai precisar do VMA (Vulkan Memory Allocator) para gerenciar alocações de memória GPU de forma eficiente. Depois de clonar o repositório, o comando de build típico é algo como:
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc) Isso gera um executável de amostra na pasta build/samples/ que mostra um cubo rotacionando com iluminação PBR. Esse sample é útil para validar se o ambiente está funcionando antes de partir para seu próprio projeto.
Para integrar o White Castle como dependência em outro projeto, a recomendação é usar o FetchContent do CMake ou copiar as pastas core/, renderer/, e ecs/ diretamente. A primeira opção é mais limpa; a segunda evita problemas de rede em ambientes corporativos.
Por dentro do pipeline gráfico
O renderer do White Castle segue um modelo forward+ com Shadow Map Multi-Part e suporte a UBOs para buffers de uniforme. A cena é definida através de um SceneManager que gera um G-Buffer durante a fase de geometria. Diferente de engines maiores, não há sistema integrado de pós-processamento complexo — você implementa os passes de pós que precisa manualmente usando quad fullscreen com shaders customizados. Um ponto importante que muitos ignoram: o White Castle não inclui um sistema de física embutido. Você precisa integrar manualmente uma biblioteca como Jolt Physics, Bullet ou PhysX. Eu usei Jolt porque a integração via ECS é mais direta — basta criar um sistema que atualiza transformações baseado nos resultados de detecção de colisão a cada frame. Funciona bem, mas exige que você gerencie o step de física separadamente do render tick, caso contrário os objetos vão pular frames visuais de forma irregular.
👉 Clique no botão abaixo para saber mais sobre o assunto!
A carga de assets segue um modelo baseado em arquivos .wci (White Castle Import), que é basicamente JSON com referências a mesh files em OBJ ou glTF. A conversão de glTF para .wci é feita pela tool de linha de comando incluída no repositório. Ela extrai buffers BIN do glTF, converte UVs e normais, e gera o arquivo de scene. A tool tem limitação conhecida: meshes com mais de 65535 vértices precisam ser subdivididos manualmente antes da conversão, senão o processo falha silenciosamente.
Problema real que encontrei e solução
Em um projeto de simulação para visualização industrial, encontrei um bug específico onde sombras multi-câmera distorciam drasticamente quando a luz direcional estava em ângulo inferior a 5 graus em relação ao plano XZ. O resultado era artefatos de Z-fighting massivos nas shadow maps. O problema estava no cálculo do frustum da luz — o White Castle usa umortho projection fixa para directional lights, e o near plane era calculado de forma ingênua sem considerar a projeção praticamente planar do cenário. A correção foi fazer um patch no arquivo src/renderer/LightManager.cpp, substituindo a lógica de cálculo do view matrix da luz por uma versão que projeta os oito vértices do AABB da cena no espaço da luz e recalcula o frustum com base neles. O código ficou em torno de 40 linhas adicionais. Compilou sem problemas e os artefatos sumiram completamente. Esse tipo de ajuste manual é o padrão quando se trabalha com o White Castle — a engine fornece a base, mas cenários específicos exigem modificações no núcleo.
Pontos fortes e limitações reais
O White Castle brilha em projetos que precisam de um renderer customizado com controle fino sobre o pipeline, mas não querem a complexidade de uma engine completa. O código é legível, bem estruturado, e fácil de estender. O sistema ECS também permite paralelização natural de sistemas, o que ajuda em hardware multi-core. Por outro lado, a falta de ferramentas de edição visual é uma desvantagem séria. Não há editor de cenas integrado — você define tudo por código ou arquivos de cena JSON. Isso significa que designers e artistas ficam completamente excluídos do processo. Para equipes pequenas que trabalham sozinhas, isso é gerenciável. Para times maiores, vira gargalo rapidamente.
O suporte a animação também é básico. Skinning de malhas animadas funciona, mas não há sistema de animation blending, state machines visuais, ou preview de animações dentro da engine. Você depende de ferramentas externas como Blender para criar e exportar animações, e depois chama os métodos de playback da API diretamente. Performance em scenes grandes com muitas entidades dinâmicas também cai de forma pronunciada acima de 50 mil entidades ativas. O scheduler do ECS não faz culling automático por distância ou visibility frustum — isso é responsabilidade sua. Implementar um sistema de occlusion culling próprio resolve parcialmente, mas adiciona complexidade significativa.
Alternativas para considerar
Se o seu projeto precisa de editor visual, pipeline completo de animação, e maduro, engines como Godot ou Amplify Engine são opções mais práticas, mesmo com overhead maior. Se precisa de controle baixo nível mas com mais material de apoio e exemplos, o SDL3 com Vulkan raw pode ser mais simples do que adapter o White Castle para seus propósitos. O White Castle funciona bem como base educacional ou como ponto de partida para um renderer customizado quando você já conhece bem o pipeline gráfico. Não é uma solução pronta para produção em larga escala, mas é honesto sobre o que oferece e deixa claro onde suas limitações estão.
