Skip to content

feat(clothing): pipeline de roupas WrapLayer, personalizacao do personagem e cages 3D - #57

Merged
Ak4ai merged 160 commits into
mainfrom
wip/roblox-ground-truth
Oct 10, 2026
Merged

Ak4ai merged 160 commits into
mainfrom
wip/roblox-ground-truth

Conversation

@Ak4ai

@Ak4ai Ak4ai commented Oct 10, 2026

Copy link
Copy Markdown
Owner

Descricao

Consolida o pipeline de criacao de personagem e encaixe de roupas:

  • Encaixe dinamico com cages 3D de referencia e WrapLayer adaptativo (feminino e masculino)
  • Otimizacao do HSR (Hidden Surface Removal) para ocultacao precisa de pele sob as roupas
  • Interface e sistema de customizacao de avatar (/skin), proporcoes corporais, cabelos e cosmeticos
  • Animacoes de caminhada com suporte a vestuario multicamadas
  • Suite de testes automatizados e validacoes de robustez

… WrapLayer

Ponto de recuperação local antes de integrar o radial + prisma no runtime.

- Importador FileMesh v4/v5 grava só o LOD0 (antes juntava todos os LODs
  e a peça era desenhada várias vezes sobreposta); cache de roupas vestidas
  sobe para v8 para forçar regeneração.
- wrap_layer_fit: aceita cages de referência com contagem de triângulos
  diferente de 2690 (pareamento já é feito por UV) — regata passa a vestir.
- Scripts de comparação contra exports OBJ do Roblox Studio no Blocky
  (compare_roblox_ground_truth, batch_compare_roblox, closeup, variantes,
  auditorias de globalidade, resíduo do prisma, rotação e esticamento).
- Inclui o trabalho de auditoria anterior (wrap_layer_fit, multi_influence_shell,
  módulos experimentais, testes e artifacts/clothing_audit) que não estava
  versionado.
Algumas cages externas do catálogo têm poucos UVs editados em relação à
cage de referência (Boxy Shirt e Kemeja Boxy: 16 de 1709). O pareamento por
UV mais próximo ficava ambíguo e a peça caía no encaixe antigo. Agora os
pontos exatos pareiam por UV e os divergentes pelo vizinho: cada ponto vai
para o ponto externo cujos vizinhos são os pares dos seus vizinhos. Limite
de segurança: no máximo 2% dos UVs divergentes.
…or prisma

O encaixe das peças com cages (corpo feminino) passa a usar o método validado
contra exports do Roblox Studio no Blocky: cage externa transferida por
influências radiais, cada vértice localizado no prisma entre cage interna e
externa, e partes penduradas (fitas, laços) mantendo a direção original.
Se o novo encaixe falhar, o runtime mantém o encaixe por triângulo anterior.

Contra o Roblox (vértices a mais de 5 cm): vestido 14,6% -> 6,5%,
saia-short 22,3% -> 6,7%, jeans 15,3% -> 6,7%, camisa 5,3% -> 0,6%,
calça skater 18,6% -> 14,2%, cargo 12,2% -> 9,6%; jaqueta piora 7,1% -> 10,3%.
Custo: +2 a 4 s na primeira vez que cada peça é vestida (depois fica em cache).
Cache de roupas vestidas sobe para v9.
Decodifica o HiddenSurfaceRemovalAsset de cada roupa (HSRAssetId do WrapLayer):
HSRData traz 1 bit por vértice da cage de referência (bit 0 = pele coberta).
A máscara vai para a cage do corpo feminino pelo mesmo pareamento de UV do
WrapLayer e fica salva ao lado do OBJ vestido (*_hsr.npz). Validada contra os
exports do Roblox Studio no Blocky: concorda com a pele que o Studio esconde
em 85-100% da área do corpo (9 de 10 peças; o suéter de cage anômala fica em 63%).

Quando todas as peças vestidas têm máscara, o CharacterModel desenha tronco,
pernas e braços inteiros e remove só os triângulos cobertos; as mãos ficam
inteiras. Sem máscara em alguma peça, os cortes por regra continuam.
Cache de roupas vestidas sobe para v10.

Também corrige o script de render que apagava o cache masculino do suéter
padrão (causa da falha intermitente em test_parse_obj_as_mesh_sweater).
…m radial + prisma

A validação do WrapLayer exigia a roupa a no máximo 0,05 (mediana) / 0,2 (p99)
da cage externa — um limite para o encaixe por triângulo, que extrapola mal
longe da cage. O radial + prisma trata pontos distantes (resíduo do prisma e
partes penduradas), então passa a exigir só cage transferida sem distorção
(esticamento p99 <= 2,5) e mediana <= 0,1. Se ele falhar numa peça que só ele
aceitaria, a peça volta ao encaixe anterior. Passam a vestir: saia-short,
camiseta 76ers, suéter Brooklyn, camisa cropped e moletom; o suéter oversized
de cage anômala continua recusado (esticamento 4,6).

Peças soltas da malha (fitas e laços separados da saia) agora penduram do ponto
preso mais próximo no espaço: saia-short contra o Roblox 6,7% -> 1,4% dos
vértices a mais de 5 cm; as demais peças não mudam. Cache sobe para v12.
O wear() espelhava em X toda roupa feminina com WrapLayer, mas o encaixe pelas
cages já sai na orientação do corpo (confere com o Roblox no Blocky). O
espelho extra invertia estampas e textos (IVERSON, RULE). O espelho continua
só no encaixe antigo. Cache sobe para v13.
…guro

Testadas 35 roupas em camadas novas do catálogo (5 por categoria):
- Cage de referência com poucos triângulos colapsados (área zero): os pontos
  sem referencial pegam o deslocamento dos vizinhos (até 2% dos pontos).
- Cage externa com pontos apagados pelo criador: esses pontos da referência
  ficam sem par e herdam a espessura dos vizinhos.
Resultado: 29 de 35 vestem pelo radial + prisma; 5 fantasias gigantes são
recusadas pela validação e 1 (Baby Shark, 480 pontos colapsados) continua com erro.

HSR:
- Só a versão 0x12 do HSRData é usada; as 0x10/0x11 lidas do mesmo jeito espalham
  a máscara pelo corpo (coerência espacial 0,5-0,8 contra 0,84-1,0) e furavam a pele.
- A pele é subdividida (2 níveis) e cada vértice é projetado na superfície da cage;
  um triângulo só some quando os 3 vértices estão cobertos. Concordância com o
  Studio igual à regra anterior (±1,5 pt) sem abrir buracos nas malhas simples.
Cache sobe para v15.
Roupas com HSR antigo (0x10/0x11, 22 das 56 do cache) ou fora do WrapLayer
caíam nos cortes por regra, que supõem camisa comum: jaqueta aberta de ombro de
fora escondia o tronco inteiro, mangas soltas de ombro de fora flutuavam e
shorts escondiam as pernas inteiras.

Agora o wear() deriva a pele coberta da própria roupa vestida: um ponto da cage
do corpo fica coberto quando há vértice da roupa a até ~4,9% da altura do corpo
e no máximo ~2% para dentro da pele. Contra o Roblox Studio no Blocky concorda
em 84-96% da área (a máscara oficial 0x12: 85-100%). Cache sobe para v17.
As roupas pareciam soltas porque a pele era cortada exatamente até o limite da
máscara e sobrava fresta entre a barra e a pele (shorts, jaqueta aberta, mangas
de ombro de fora). Contra o Roblox, a máscara geométrica escondia 4-14% de pele
que o Studio mostra.

- Um ponto da pele só some quando a máscara interpolada na cage passa de 0,9
  (antes 0,5): a pele avança cerca de um triângulo da cage sob cada borda.
- Raio da máscara geométrica 4,9% -> 3% da altura: fresta média 5,6% -> 2,3%
  da área do corpo, concordância com o Studio 86% -> 80% (o resto é pele a
  mais sob o tecido, que o tecido cobre).
Cache sobe para v18.
…o zíper

- Runtime usa radial + prisma sempre que as cages pareiam; o validador antigo
  só decide o fallback por triângulo (Mafioso, dino, slime, Sully, múmia,
  gato, pombo e macacões passam a vestir certo).
- Pareamento de UV da cage externa não falha mais em pontos sem par; pontos
  órfãos até 5% e preenchimento pelo vizinho mais próximo.
- Máscara HSR geométrica por raio (passa pela fenda do zíper) e esconde pontos
  visíveis isolados vistos por furinhos do tecido (ilhós do cordão).
- Cache de roupas v21.
Top e calça são encaixados no corpo separadamente, e o cós da jeans ficava
1-2 mm para fora da barra do moletom nas costas, aparecendo como um buraco
preto. Ao montar o personagem, os vértices da calça que furam o top (até 1 cm)
ou encostam nele são puxados 4 mm para dentro. Se a maior parte da calça
já está por fora (top por dentro da calça), nada muda.
…as, largas, soltas, mínimas)

- build_catalog_sample.py monta a amostra por busca no catálogo, expandindo
  bundles de sapato em pé esquerdo e direito.
- 34 peças: 27 vestem, 7 falham no pareamento/cage.
- closeup_hsr_outfit.py: close na cintura com e sem HSR; câmera dos renders
  de teste com alvo configurável.
…agora vestem)

- UVs a menos de 0,001 são o mesmo ponto (UVs do corpo ficam a >= 0,003):
  cobre ruído de precisão da calça cargo e do tomara-que-caia.
- UV da referência editado pelo autor além de 0,01 é pareado ao corpo por
  conectividade, como já era feito na cage externa (saia com fenda).
- Cage externa pode perder até 35% dos pontos (puffer, moletom oversized);
  uma parte inteira faltando herda a espessura do ponto conhecido mais próximo.
- Pontos só em triângulos colapsados até 35% (Baby Shark).
- Triângulos degenerados da cage externa saem da projeção em vez de abortar
  (bota de pelo).
- Cache de roupas v22: peças que falhavam estavam no cache com o encaixe antigo.

As 48 peças que já vestiam têm métricas idênticas.
O caminho sem HSR não desenhava pés quando havia calça (a jeans padrão tem
botas). Calças que não chegam ao chão agora mostram os pés; as que chegam
(botas, meia-calça, barra comprida) seguem cobrindo.
…izinhas

Cada vértice pendurado copiava o deslocamento de uma única âncora; vizinhos
presos a âncoras diferentes se separavam (97 de 126 arestas rasgadas da saia
com fenda). O deslocamento agora é interpolado harmonicamente pela malha a
partir dos vértices presos; pedaços soltos seguem rígidos.

Saia com fenda: 126 -> 25 arestas esticadas >3x; vestido longo: 156 -> 59.
Contra o Roblox Studio (10 peças): nenhuma piora; vestido, saia-short e
suéter um pouco mais perto. Cache de roupas v23.
…a de fora)

Top e calça são encaixados no corpo separadamente; onde a calça atravessava
um casaco comprido (jaleco, sobretudo) ou a barra de um moletom, ela aparecia
por cima. Agora a peça de fora fica intacta e os vértices da de dentro que a
furam são puxados 5 mm para baixo dela, ao longo do raio a partir do eixo do
corpo (normais não servem: o forro do cós aponta para dentro).

- Jaqueta, suéter e vestido ficam sempre por fora (como no Roblox); outros
  tops ficam por fora a menos que a calça já esteja por fora da maior parte
  deles (camisa por dentro da calça).
- O tipo do asset vai no cabeçalho do OBJ encaixado (cache v24).
- Pontos da calça furando: jaleco 1055 -> 0, sobretudo 227 -> 0,
  moletom 24 -> 0; a calça anda 1 cm na mediana, sempre sob o casaco.
- Substitui tuck_inner_layer.
- CharacterModel(outer_top_id=...) veste uma segunda peça por cima do top
  (corpo feminino); a máscara de HSR dela entra no recorte da pele.
- Camisa e calça que furam a peça de cima são puxadas 1,5 cm para baixo
  dela, ao longo do raio que sai da cage do corpo (vale para braços, ombros
  e peito, não só a cintura); triângulos totalmente cobertos são escondidos.
- Vazamento medido em pixels (peça de baixo em vermelho, 4 vistas):
  camisa+bomber 10406 -> 1681, cropped+jaleco 11984 -> 3171,
  camisa+sobretudo 22058 -> 4449, regata+moletom 903 -> 507.
- Ainda vaza nas lapelas de casacos; o caminho do Roblox é encaixar a peça
  de cima sobre a cage externa da de baixo.
Como no Roblox, a jaqueta é encaixada sobre a cage externa já transferida
da camisa em vez do corpo nu: RobloxWearEngine.layer_under_asset encaixa a
peça de baixo, pega a cage externa transferida (radial) de cada ponto UV do
corpo e a usa como corpo alvo (retarget_garment_with_wrap_layer ganhou
target_positions). Cache por par: character_native_<cima>_over_<baixo>_female.obj.

Com a camisa pintada de vermelho, a bomber e o moletom ficam limpos e o
jaleco e o sobretudo deixam só pontinhos (antes vazavam nas lapelas).
O puxão/esconder continua como rede de segurança.
…amadas

- /jaqueta <ID|none> veste uma peça por cima do top no jogo.
- /jaqueta folga <mm> afasta a jaqueta da camisa: a cage externa da camisa
  é inflada ao longo das normais antes do encaixe (como o Puffiness do
  WrapLayer); reencaixa, com cache por valor (_g<mm>). Padrão 5 mm.
- /jaqueta puxar <mm> ajusta quanto a camisa entra por baixo onde ainda
  fura (sem reencaixe). Padrão 15 mm.
- Camisa + sobretudo: manchas da lapela somem com 10 mm; jaleco idem.
O sobretudo era encaixado sobre o corpo nu nas pernas e a jeans o furava nas
costas do quadril. Agora a camada de cima é encaixada sobre as cages externas
de todas as peças de baixo (em cada ponto vale a casca mais externa):
- peça por cima do top: sobre o top e a calça;
- casaco, suéter ou vestido usado como top: sobre a calça
  (cache character_native_<top>_over_<calça>[_g<mm>]_female.obj).
- CharacterModel(shoes_id=...) veste um bundle de calçado (ou "esq,dir");
  cada pé passa pelo pipeline de cages, e a máscara HSR deles entra no
  recorte da pele. Os pés de bloco são escondidos sob o calçado (são mais
  largos que um salto ou tênis fino).
- Encaixe próprio de calçado: o pé é rígido (rotação da cage inteira, escala
  e posição do pé da cage), porque o encaixe por prismas amassava o tênis
  no nosso pé-caixa achatado e quebrava o salto; acima do tornozelo o cano
  mistura com o encaixe por cage para envolver a panturrilha.
- Testados: tênis, botas, salto alto, bota de pelo, bota plataforma.
- /sapato <bundle | esq,dir | none>. Cache de roupas v29.
…or anéis

scripts/build_male_cage.py monta a cage R15 masculina a partir da feminina
(mesma topologia e UVs, para toda roupa parear igual), uma parte por vez.
Os corpos não compartilham ordem de vértices e as partes têm formas
diferentes, então cada ponto é descrito pela altura relativa na parte e pela
posição relativa ao corte da pele naquela altura (casco convexo, centro,
meia largura/profundidade) e reconstruído no corpo masculino.

Tórax (UpperTorso, 231 pontos): distância à pele 1,2 cm de mediana (fem
1,1), máx 4,7 (fem 4,3); nas fatias de 10% a 90% o anel da cage envolve a
pele inteira, inclusive nos ombros mais largos do masculino.
…o pescoço

- Verificação nos dois sentidos: pele furando a cage (amostras da pele sob um
  triângulo da cage, medidas pela normal da pele) e pontos da cage dentro da
  pele; só pele visível (a base do pescoço enterrada no tórax não conta).
- Transferência por deformação suave do espaço (RBF biharmônica) ajustada
  da pele feminina para a masculina (tórax + pescoço, pareados por anéis).
- Colarinho: pontos presos ao pescoço seguem o centro do pescoço e o topo do
  ombro rigidamente (o pescoço masculino fica mais atrás e o ombro mais alto).
- Colisões restantes resolvidas inflando a cage de forma suave (empurrão
  espalhado pelos vizinhos, costuras de UV unidas).
- Render: corpo sem cabelo, marcas vermelhas/amarelas de colisão e close do
  pescoço (--pescoco).

Resultado: 0 de 535 amostras furando, 0 pontos dentro; distância à pele
1,25 cm de mediana (fem 1,07).
…uinas do corpo)

Depois da deformação suave, cada ponto da cage é projetado na superfície à
mesma distância da pele que tinha no feminino: o ponto mais próximo cai sobre
as quinas do corpo, e a silhueta da cage passa a acompanhar as bordas do
tórax masculino em vez de arredondá-las. O colarinho fica fixo. Testei também
relaxamento entre projeções; ele embaralhava os anéis e foi desligado.

0 colisões; distância à pele 1,45 cm de mediana (fem 1,07).
Ak4ai added 26 commits October 9, 2026 11:01
… do globo

Os formatos achavam os cílios pelo quanto o pixel é escuro: uma íris de cor
escura era tomada por cílio e cortada junto. Agora cada pixel leva o que ele é
(cílio, globo ou nada), dito pelo desenho original; a pálpebra que desce leva
os cílios inteiros e os desenha por cima do globo.
…ao longo da linha da máscara

- A pele mantida que encosta no tecido ou sai dele (a quina do tronco no crop
  top: um risco de pele no peito) é levada para logo abaixo do tecido.
- A pele é cortada ao longo da linha da máscara, não por triângulos inteiros,
  onde o tecido cobre o que é cortado: menos pele furando na pose de vestir.
- Medido na bateria de robustez em oito peças nos dois corpos; nada piorou.
  Três outras regras foram tentadas e deixadas de fora (ver a wiki).
No modo terreno o personagem era sempre montado em segundo plano; uma captura
com poucos quadros saía com o aviso "Atualizando personagem..." e sem o
personagem. Como no modo personagem, a captura agora espera a montagem.
… ponto só

As pontas dentro da cava do crop top eram da roupa: o encaixe espalhava as
cópias do vértice do meio do leque que fecha a cava (até 28 cm), e o leque
virava um estouro de espinhos. keep_together junta essas cópias depois do
encaixe; scripts/weld_fitted_fans.py aplica o mesmo às roupas já encaixadas.
Só leques (8 cópias ou mais): juntar também as costuras de UV piorou 12 peças.
…lar calada

Sem memória, todas as combinações depois da sétima falharam sem aviso e o
relatório saiu como se o catálogo tivesse sete peças.
- Removidos quatro scripts que já não rodavam (importavam módulos de
  experimento apagados em 06/10).
- A proposta do motor universal de roupas sai da raiz e vira página histórica
  da wiki.
- Nova página "Scripts do Projeto": para que serve cada script e se ainda é
  usado. Pendências atualizadas com o estado de 10/10.
Os cabelos nudred e raspado e as cabeças de referência ficam no arquivo, fora
do viewport e do render; a cena abre mostrando só o corpo feminino do jogo.
… do repositório

Ficam em scripts/ só os 14 que o jogo, a CI e as ferramentas da wiki usam.
Os outros 57 scripts, os nove módulos experimentais de src/clothing, os doze
arquivos de teste deles (51 testes) e o manequim de referência do Roblox
foram para backup/, que o git ignora. A wiki lista o que há lá e como trazer
de volta.
O único teste que o usava testava a própria função experimental, não o
encaixe do jogo. Ficam 13 scripts e 665 testes no repositório.
Estavam ignorados (*.obj) e só existiam nesta máquina: num clone limpo, 27
testes falhavam e o corpo feminino não tinha malha nem cages. Com estes oito
arquivos o jogo abre nos dois corpos a partir de um clone.
…itório

Doze .fbx e o pacote stage 2, que nada lê, vão para backup/. A wiki passa a
dizer quais malhas ignoradas pelo .gitignore um clone precisa.
Sem credencial do Roblox o download de roupas responde 401, então um clone só
tem as roupas que vêm no repositório. As 32 peças de exemplo tinham o .rbxm e
a textura no git, mas não a malha de origem (*.obj é ignorado): entram as 52
malhas que faltavam. Saem do git 56 arquivos que nenhuma delas lê (caches de
máscaras de outras peças, cages antigas, texturas soltas); continuam no disco.
Os Hair_fitted_<id>_<corpo>.obj dos cabelos de exemplo são refeitos ao vestir
(e reescritos a cada vez); ficam só o padrão, o nudred e o raspado. O teste
do suéter passa a ler a malha do catálogo, não um cache antigo.
…do repositório)

Num clone recém-criado o .obj da cage ainda não existe: é um cache.
Traz a grade tática, a correção da câmera e os ajustes de streaming do
terreno. Um conflito, em src/main.py, resolvido mantendo os dois lados: o
modo personagem e o editor (deste branch) e a grade do terreno (do main).
A origem do corpo fica acima da planta do pé e a sola de um tênis desce 6 a 7
cm: os pés afundavam no chão. O animador mede o ponto mais baixo do que o
corpo pisa (os calçados, ou os pés) e sobe o corpo isso, a cada montagem.
…eça careca

O botão "Padrão" dá ao modelo o id do cabelo padrão; a montagem limpava a
malha do padrão e só a repunha quando nenhum cabelo tinha sido escolhido. O
padrão volta também a ser desenhado na cor de cabelo do personagem.
@Ak4ai
Ak4ai enabled auto-merge October 10, 2026 07:48
@Ak4ai
Ak4ai merged commit e282ae0 into main Oct 10, 2026
1 check passed
@Ak4ai
Ak4ai deleted the wip/roblox-ground-truth branch October 10, 2026 07:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant