> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Depuração com pastas de sobreposição

> Como usar pastas de sobreposição para depurar e iterar localmente em alterações de títulos sem modificar arquivos na estrutura de pastas subjacente no disco.

# Pastas de sobreposição

<Note>
  Em geral, o Tools SKU permite atualizar as ferramentas do GDK sem precisar atualizar outros componentes do GDK (por exemplo, cabeçalhos, bibliotecas e Game OS). O recurso de pastas de sobreposição é uma exceção, pois depende do suporte do Game OS, que é lançado como parte do GDK, mas não do Tools SKU.
</Note>

## Usos canônicos de pastas de sobreposição

As pastas de sobreposição são adequadas para cenários em que um desenvolvedor de jogos deseja atualizar localmente um único arquivo, ou alguns arquivos, de um título, mas manter intacto o armazenamento subjacente dos arquivos originais do jogo. Considere os exemplos a seguir.

* Abigail está testando uma versão empacotada do título dela no XBOX One ERA Development Kit. Ela encontra um bug no título e conhece a causa raiz. Ela corrige rapidamente o código problemático localmente no PC de desenvolvimento. No kit de desenvolvimento, ela cria uma pasta de sobreposição associada ao pacote do título. Ela copia o executável que contém a correção para a pasta de sobreposição, inicia o título e consegue verificar imediatamente que a correção resolveu o bug. Isso acelera drasticamente o tempo de iteração. Antes, ela precisava reempacotar o título inteiro e reimplantar o pacote no console para poder testar esse tipo de correção.
* Felix mantém um laboratório de playtest em que os kits de desenvolvimento são configurados para executar diversos jogos sob demanda, pela rede do estúdio, a partir de builds de arquivos soltos armazenados em um servidor de build centralizado (usando o modelo de implantação Executar a partir de um PC). Um dos playtesters descobre um bug grave. Um desenvolvedor fornece um .dll privado a Felix, que o configura em uma pasta de sobreposição em uma das máquinas do laboratório. Com o .dll privado sobreposto, o jogo agora é executado sem problemas. Felix conseguiu testar a correção localmente em um kit de desenvolvimento sem precisar modificar a versão do jogo compartilhada na rede, reduzindo o risco de atrapalhar outros playtesters.

As pastas de sobreposição foram projetadas para permitir alterações rápidas e iterativas em um título, mesmo quando o pacote original usado para instalar o título não está disponível ou não pode ser modificado.

## Conceitos de pastas de sobreposição

Usando uma pasta de sobreposição, um desenvolvedor pode *sobrepor* ou substituir a versão de um arquivo em um jogo por uma versão alternativa armazenada em outro local, inclusive como arquivo solto em uma unidade local ou em algum lugar da rede. Os principais conceitos que você precisa entender para usar pastas de sobreposição com êxito são os seguintes:

* **Set:** associa o nome completo do pacote do seu jogo ao caminho de uma pasta onde seus arquivos de sobreposição serão armazenados. Quando definidos, o nome completo do pacote e o caminho formam essencialmente um par chave-valor que persiste entre reinicializações do kit de desenvolvimento.
* **Get:** recupera o caminho da pasta de sobreposição atualmente associado a um nome completo de pacote específico.
* **List:** lista todos os pares de nome completo do pacote (PFN)/caminho da pasta de sobreposição registrados no kit de desenvolvimento.
* **Clear:** você pode limpar (também conhecido como *redefinir*) a pasta de sobreposição de um nome completo de pacote específico ou de todos os nomes completos de pacote. Isso simplesmente remove qualquer caminho de pasta de sobreposição associado anteriormente ao nome completo do pacote.

Vamos usar um exemplo para ilustrar esses conceitos. Omar está testando um jogo chamado MyGame. O executável principal do jogo é MyGame.exe, e ele é instalado como parte da parte de inicialização do jogo. Outras partes do jogo podem ser carregadas enquanto o jogo está em execução, portanto, elas estão em partes transmitidas para o console depois que a parte de inicialização é instalada. installlazily.dll é um binário que pode ser transmitido para o console depois que o jogo é iniciado. Uma desenvolvedora, Eugenia, corrigiu alguns bugs no build empacotado de MyGame da noite anterior e gostaria que Omar testasse as correções. Ele pode se preparar para testar as correções facilmente, mesmo sem pedir a Eugenia que reempacote MyGame, usando uma pasta de sobreposição da seguinte maneira.

1. Omar usa o prompt de comando do GDK para criar uma nova pasta na unidade de rascunho do sistema do kit de desenvolvimento XBOX.
   ```text theme={null}
   @REM Create the overlay folder on the devkit's system scratch drive.
   mkdir \\MyDevKit\SystemScratch\MyGameOverlay\
   ```
2. Em seguida, ele copia os binários corrigidos para a pasta de sobreposição recém-criada.
   ```text theme={null}
   @REM Copy two files to the overlay folder on the console.
   copy c:\Development\MyGame\game.exe \\MyDevKit\SystemScratch\MyGameOverlay\
   copy c:\Development\MyGame\installlazily.dll \\MyDevKit\SystemScratch\MyGameOverlay\
   ```
3. Depois, Omar define a pasta como a pasta de sobreposição do jogo.
   ```text theme={null}
   @REM Register the overlay folder for the package. Because it's in the scratch drive, it's relative to D:\ on the console
   xbapp overlayfolder MyGame_1.0.0.0_neutral__cw5n1h2txyewy xD:\MyGameOverlay
   ```
4. Por fim, ele instala a parte de inicialização do build do pacote da noite anterior.
   ```text theme={null}
   @REM Install the package's launch chunk and register the game.
   xbapp install /l c:\Development\MyGame\Packages\MyGame_1_0_0_0.xvc
   ```
5. Agora ele está pronto para testar. Ele inicia o jogo normalmente.

Quando o jogo é iniciado, o game.exe da pasta de sobreposição é carregado (ou seja, não o game.exe copiado para o console como parte da parte de inicialização do pacote). Depois que a instalação por streaming avança até o ponto em que a parte que contém installlazily.dll é instalada, o jogo é notificado de que a parte está disponível e carrega installlazily.dll. A versão de installlazily.dll da pasta de sobreposição será carregada. Como resultado, os binários corrigidos da pasta de sobreposição permitem que o pacote não modificado seja executado corretamente, e Omar relata que os problemas foram resolvidos.

## Implicações de design

O kit de desenvolvimento faz muito trabalho de forma transparente em nome do desenvolvedor para facilitar o uso das pastas de sobreposição. Embora seja transparente, há aspectos que você deve entender para maximizar os benefícios das pastas de sobreposição.

### Fluxo de trabalho flexível

No exemplo anterior, Omar decidiu configurar primeiro a pasta de sobreposição e depois instalar o build empacotado da noite anterior. Ele poderia muito bem ter decidido instalar o pacote primeiro. Desde que a pasta que contém os arquivos de sobreposição exista e esteja acessível, a pasta de sobreposição tenha sido definida para associar o nome completo do pacote do jogo ao caminho da pasta de sobreposição e o jogo esteja instalado/registrado no momento em que o desenvolvedor tentar iniciá-lo, os arquivos da pasta de sobreposição serão usados para executar o jogo. A ordem dessas operações fica a critério do desenvolvedor.

* O jogo não precisa estar instalado/registrado no momento em que a pasta de sobreposição é definida.
* O diretório referenciado no caminho da pasta de sobreposição não precisa existir nem estar acessível quando a pasta de sobreposição é definida.
* Novos arquivos e diretórios adicionados à pasta de sobreposição, inclusive durante a execução do jogo, são usados nas chamadas FileOpen subsequentes enquanto o jogo é executado.
* Não há efeito colateral causado pela desinstalação/reinstalação do jogo depois que a sobreposição é definida.

<Note>
  No momento, não há suporte para substituir o MicrosoftGame.config do seu título em uma pasta de sobreposição.
</Note>

### Escolha das ferramentas de desenvolvimento

No exemplo anterior, Omar criou um diretório no kit de desenvolvimento XBOX e copiou arquivos para ele usando o prompt de comando do GDK (ou seja, usando mkdir e copy). Em vez disso, ele poderia ter optado por usar outras ferramentas.

* Ferramentas remotas do GDK (por exemplo, xbdir e xbcp)
* Ferramentas gráficas do Windows (por exemplo, o Explorador de Arquivos)
* Comandos do shell Bash
* Ferramentas de terceiros

Da mesma forma, Omar definiu a pasta de sobreposição usando xbapp na linha de comando. A configuração de pastas de sobreposição também tem suporte por meio dos seguintes recursos:

* XBOX Manager
* XBOX Device Portal
* Developer Home (Dev Home)
* API do XBOX Tools Framework

### Operação e diagnóstico transparentes

#### Indicador visual

É fácil "definir e esquecer" uma pasta de sobreposição. Depois que uma pasta de sobreposição é definida, arquivos e diretórios dentro dela podem ser adicionados/atualizados/removidos sem alterar a configuração da pasta de sobreposição. Por isso, fornecemos indicações visuais nas ferramentas gráficas para lembrar proativamente os desenvolvedores de que eles definiram uma pasta de sobreposição para um título.

#### Saída de depuração

Quando um jogo é ativado e há uma pasta de sobreposição definida para o nome completo do pacote dele, uma saída de depuração é gravada para indicar que uma sobreposição foi encontrada, e os arquivos carregados da pasta de sobreposição também são exibidos.

## Configurar pastas de sobreposição

### Configurar uma pasta de sobreposição pela linha de comando

Conforme mostrado na seção anterior deste tópico, uma pasta de sobreposição para um nome completo de pacote especificado pode ser recuperada, definida, atualizada e redefinida usando o comando [xbApp overlayfolder](/pt-BR/tools/tools-console/commandlinetools/xbapp).

### Configurar uma pasta de sobreposição pelo XBOX Manager

O XBOX Manager permite exibir, adicionar e excluir o caminho da pasta de sobreposição de um nome completo de pacote. Para obter mais informações, confira [Gerenciar aplicativos e arquivos (XBOX Manager)](/pt-BR/tools/tools-console/xbom/manager-tool-managing-applications).

### Configurar uma pasta de sobreposição pelo XBOX Device Portal

O XBOX Device Portal permite exibir, adicionar e excluir o caminho da pasta de sobreposição de um nome completo de pacote. Para obter mais informações, confira [Gerenciar pastas de sobreposição (XBOX Device Portal)](/pt-BR/tools/tools-console/wdp/windows-device-portal-on-xbox-overlay-folders).

### Configurar uma pasta de sobreposição pelo Dev Home

O Dev Home permite exibir, adicionar e excluir o caminho da pasta de sobreposição de um nome completo de pacote. Para obter mais informações, confira [Gerenciar pastas de sobreposição (Dev Home)](/pt-BR/tools/tools-console/devhome/devhome-overlay-folders).

### Configurar uma pasta de sobreposição usando a API do XBOX Tools Framework (XTF)

O XTF permite consultar, adicionar e limpar o caminho da pasta de sobreposição de um nome completo de pacote. Para obter mais informações, confira [APIs adicionais do Xtf](/pt-BR/reference/tools/xtf/xtfapi/atoc-xtfapi).

### Configurar caminhos relativos ao console

Os caminhos de pastas de sobreposição têm uma visão relativa ao console. Ao especificar E:\Overlay, o console procurará E:\Overlay no System OS e não o encontrará. Isso se deve à forma como as sobreposições são processadas: o System OS e o Title OS, e não as ferramentas do PC, são responsáveis por processar as sobreposições.

Para configurar corretamente sua pasta de sobreposição, use as diretrizes abaixo.

* Você pode compartilhar a pasta de sobreposição via SMB e depois usar o caminho \FQDN\_PC\_NAME\shared\_overlay:
  * Exemplo: `xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw \FQDN_PC_NAME\shared_overlay`
  * OBSERVAÇÃO: o console precisará de credenciais para o compartilhamento SMB via `xbcred add FQDN_PC_NAME\shared_overlay FQDN\USER_NAME PASSWORD`
  * OBSERVAÇÃO: use o nome de domínio totalmente qualificado em todas as referências a esse caminho para evitar problemas de resolução de nomes.
* Você pode usar Executar a partir do PC via XBTPLink, usando xbtp:\FQDN\Q:\overlay
  * Exemplo: `xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw Q:\overlay`
  * OBSERVAÇÃO: você precisará garantir que o XbtpLinkSvc.exe esteja iniciado e que o firewall permita a conexão à porta TCP 4201.
  * OBSERVAÇÃO: em versões do GDK anteriores a outubro de 2021, era necessário usar xbtp:\FQDN\_PC\_NAME\ para criar o caminho xbtp para a pasta de sobreposição. Isso não é mais necessário; basta especificar o caminho para a pasta de rede.
* Você pode usar o D:\ no System OS, copiando os arquivos via xbcp: `xbcp Q:\overlay\mygame.exe xd:\overlay\`
  * Exemplo: `xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw xD:\overlay`
  * OBSERVAÇÃO: nesse caso, você usará xD:\overlay para a pasta de sobreposição.

Para um pequeno número de arquivos, a pasta local do System OS (opção nº 3) provavelmente é a melhor. Ela permitirá que o console consuma a sobreposição sem ficar vinculado ao seu PC. Se você precisar substituir um número maior de arquivos, pode ser mais fácil usar a 1ª ou a 2ª opção.

### Impacto das pastas de sobreposição no desempenho

As pastas de sobreposição adicionam um pequeno custo a cada abertura de arquivo. O custo é bem menor se a sobreposição for configurada para um local do System OS (opção nº 3 na seção anterior). Isso ocorre porque cada abertura de arquivo do título em G:\ primeiro processa uma pesquisa no System OS para verificar se a pasta de sobreposição contém o caminho. Esse custo é pago independentemente de o arquivo específico ter ou não uma sobreposição.

Se a pasta de sobreposição estiver localizada no PC de desenvolvimento, o impacto no desempenho deve ser considerado comparável ao da execução de um título via Executar a partir do PC. A cada leitura de arquivo, a pasta de sobreposição será verificada para determinar se existe nela um arquivo que deva ser lido em vez do original e, em caso afirmativo, ele será transferido do PC de desenvolvimento para o kit de desenvolvimento. É recomendável usar uma pasta de sobreposição em System Scratch no kit de desenvolvimento para evitar esse custo ao usar pastas de sobreposição com implantações de pasta e instalações de pacote.

### Configurar sobreposições enquanto o título está em execução

As pastas de sobreposição são aplicadas no momento do mapeamento de volumes, portanto, será necessário reiniciar o título para aplicar uma nova sobreposição. Uma forma de configurar isso com antecedência para que seu título acesse é definir uma pasta vazia como sobreposição do título e adicionar arquivos a ela mais tarde. Essa pasta de sobreposição vazia ainda terá uma pequena sobrecarga de desempenho, conforme descrito na seção acima.

### Usar pastas de sobreposição com instalações de pacote da parte de inicialização

As pastas de sobreposição dão suporte à sobreposição de arquivos em uma instalação de pacote da parte de inicialização, em que apenas uma parte do pacote é instalada. Nesse cenário, `xbapp install` deve ser executado com o sinalizador /W.

O /W é necessário para qualquer instalação em que o pacote possa solicitar partes adicionais após a conclusão do 'xbapp install' inicial. Nesse caso, as partes posteriores à parte de inicialização serão solicitadas quando o título for iniciado.

### Considerações de segurança

#### Acessar pastas de sobreposição

Quando uma pasta de sobreposição é configurada no PC do desenvolvedor, é necessário conceder explicitamente ao console permissão para acessar a pasta no PC do desenvolvedor. O serviço XRFS em execução no PC de desenvolvimento só permitirá que o console recupere arquivos de pastas locais que tenham sido adicionadas à lista de acesso dele. Uma pasta de sobreposição é adicionada à lista de acesso do XRFS usando uma linha de comando como a seguinte.

```text theme={null}
@REM On the development PC, add the local overlay folder to the XRFS Service's "allow list."
C:\>xrfssvc.exe /paths:add=C:\overlayfolders\MyGame1  
```

A definição de uma lista de permissões é necessária em qualquer cenário em que a pasta de sobreposição esteja fora do kit de desenvolvimento.

#### Acessar pastas de sobreposição em compartilhamentos de rede

Ao acessar uma pasta de sobreposição que reside em um compartilhamento de rede, é necessário garantir que credenciais de usuário com permissão para acessar o compartilhamento de rede estejam registradas no kit de desenvolvimento. Isso pode ser feito usando o comando [xbCred](/pt-BR/tools/tools-console/commandlinetools/xbcred) ou recursos equivalentes no XBOX Manager e no XBOX Device Portal.

## Confira também

* [Desenvolvimento de jogos XBOX: ambiente e ferramentas](/pt-BR/tools/tools-console/gc-tools-console-toc)
* [Implantar seu título no kit de desenvolvimento XBOX](/pt-BR/home/setup-install/concepts/deployment)


## Related topics

- [Gerenciar pastas de sobreposição](/pt-BR/tools/tools-console/devhome/devhome-overlay-folders.md)
- [XtfSetOverlayFolder](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfsetoverlayfolder-xtfapi-xbox-windows-m.md)
- [XtfClearAllOverlayFolders](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfclearalloverlayfolders-xtfapi-xbox-windows-m.md)
- [XtfGetOverlayFolder](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfgetoverlayfolder-xtfapi-xbox-windows-m.md)
- [Gerenciar pacotes (wdapp.exe)](/pt-BR/tools/tools-console/console_commandlinetools/wdapp.md)