melonjs/melonjs-carregando-assets

O que melonjs-carregando-assets faz?

Use esta skill para carregar e gerenciar assets de jogos no melonJS — o formato de descrição de recursos, a lista completa de tipos de assets, preload versus load, recuperação de assets carregados, URLs base e configurações de cross-origin, e a tela de carregamento. Aciona em: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload.

---

Formato do Descritor de Recursos

Cada asset é descrito por um objeto no formato:

{
  name: "myImage",
  type: "image",
  src: "assets/img/myImage.png"
}

• name: Identificador único do asset (usado para recuperação posterior).
• type: Tipo do asset (veja a lista completa abaixo).
• src: Caminho relativo ou URL para o arquivo do asset.

Lista Completa de Tipos de Assets

• image — formatos: PNG, JPG, GIF, WebP, SVG.
• audio — formatos: MP3, OGG, WAV, M4A.
• json — arquivo de dados JSON.
• tmx — mapa de tiles no formato Tiled (TMX).
• tsx — tileset no formato Tiled (TSX).
• gltf — modelo 3D no formato glTF.
• video — formatos: MP4, WebM, OGV.
• font — fonte bitmapped (formato melonJS .fnt + imagem).
• binary — dados binários arbitrários.

Preload vs Load

• loader.preload(): Carrega todos os assets de uma array de descritores de uma vez. É o método recomendado para carregamento inicial do jogo, pois gerencia o progresso e a tela de carregamento automaticamente.

  • Exemplo: me.loader.preload(assets, onProgress, onComplete)

• loader.load(): Carrega um único asset ou uma pequena lista sob demanda, sem gerenciamento automático de progresso. Útil para assets carregados durante o jogo.

  • Exemplo: me.loader.load({name: "extras", type: "json", src: "data/extras.json"}, onComplete)

Recuperando Assets Carregados

Após o carregamento, use os seguintes métodos para obter a referência ao asset:

• me.loader.getImage(name) — retorna um objeto Image para o asset do tipo image.
• me.loader.getJSON(name) — retorna o objeto JavaScript analisado do JSON.
• me.loader.getTMX(name) — retorna o mapa TMX analisado.
• me.loader.getGLTF(name) — retorna o modelo glTF carregado.
• me.loader.getVideo(name) — retorna um elemento HTMLVideoElement.
• me.loader.getFont(name) — retorna o objeto de fonte bitmapped.

Configurando URLs Base

Use me.loader.setBaseURL(path) para definir um prefixo de caminho para todos os assets. Exemplo:

me.loader.setBaseURL("assets/");

Isso faz com que todos os src relativos sejam resolvidos em relação a assets/.

Configurações de Cross-Origin e Credenciais

Use me.loader.setOptions(options) para configurar parâmetros de CORS e credenciais:

me.loader.setOptions({
  crossOrigin: "anonymous",      // ou "use-credentials"
  withCredentials: true,         // envia cookies/credenciais com a requisição
  credentials: "include"        // alternativa moderna (Fetch API)
});

• crossOrigin: Controla o atributo crossOrigin do elemento Image ou Audio.
• withCredentials / credentials: Define se cookies e autenticação são enviados nas requisições de rede. Essencial para assets protegidos por autenticação.

Tela de Carregamento e Evento LOADER_COMPLETE

O melonJS exibe automaticamente uma tela de carregamento (splash screen) durante o preload(). Você pode personalizá-la redimensionando o canvas ou alterando o estilo via DOM.

Após todos os assets serem carregados, o evento LOADER_COMPLETE é disparado:

me.event.subscribe(me.event.LOADER_COMPLETE, function() {
  // Iniciar o jogo ou alterar para a cena principal
  me.state.change(me.state.PLAY);
});

Descarregando Assets (unload)

Para liberar memória, use me.loader.unload(asset):

me.loader.unload("myImage");   // remove o asset pelo nome
// ou
me.loader.unload(assetObject);  // remove usando o próprio descritor

Isso remove a referência interna ao asset e permite que o garbage collector recupere a memória.