🔧 Asset Browser (v1)
Visão Geral#
O AssetBrowser é a porta de entrada para todos os recursos do projeto (texturas, sons, cenas, scripts). Na sua primeira versão (v1), o foco é a navegação no sistema de ficheiros local do projeto e a identificação de ficheiros suportados pelo motor Caffeine, especificamente ficheiros .caf (cenas) e formatos de imagem.
Este painel permite ao utilizador organizar o projeto em pastas e selecionar assets para visualização no Inspector ou para serem arrastados para a cena.
Implementação#
Estrutura da Classe#
O navegador mantém um estado do diretório atual e utiliza a biblioteca padrão do C++ (std::filesystem) para explorar o disco.
cpp
class AssetBrowser {
std::filesystem::path m_rootPath;
std::filesystem::path m_currentDirectory;
AssetHandle m_selectedAsset = 0;
public:
AssetBrowser(const std::string& root) : m_rootPath(root), m_currentDirectory(root) {}
void onImGuiRender() {
ImGui::Begin("Asset Browser");
renderPathBar();
if (m_currentDirectory != m_rootPath) {
if (ImGui::Button("<- Voltar")) {
m_currentDirectory = m_currentDirectory.parent_path();
}
}
float cellSize = 64.0f + 16.0f;
float panelWidth = ImGui::GetContentRegionAvail().x;
int columnCount = (int)(panelWidth / cellSize);
if (columnCount < 1) columnCount = 1;
ImGui::Columns(columnCount, 0, false);
for (auto& directoryEntry : std::filesystem::directory_iterator(m_currentDirectory)) {
const auto& path = directoryEntry.path();
std::string filename = path.filename().string();
ImGui::PushID(filename.c_str());
if (directoryEntry.is_directory()) {
renderFolderIcon(filename, path);
} else {
renderFileIcon(filename, path);
}
ImGui::TextWrapped("%s", filename.c_str());
ImGui::NextColumn();
ImGui::PopID();
}
ImGui::Columns(1);
ImGui::End();
}
private:
void renderFolderIcon(const std::string& name, const std::filesystem::path& path) {
// No M1 usamos botões de texto simples ou ícones ASCII
if (ImGui::Button("[DIR]", { 64, 64 })) {
m_currentDirectory /= name;
}
}
void renderFileIcon(const std::string& name, const std::filesystem::path& path) {
if (ImGui::Button("[FILE]", { 64, 64 })) {
handleFileSelection(path);
}
// Drag and Drop: permitir arrastar assets para o viewport ou inspector
if (ImGui::BeginDragDropSource()) {
std::string itemPath = path.string();
ImGui::SetDragDropPayload("ASSET_PATH", itemPath.c_str(), itemPath.size() + 1);
ImGui::Text("%s", name.c_str());
ImGui::EndDragDropSource();
}
}
};
Barra de Caminho (Path Bar)#
Uma barra clicável que permite saltar para diretórios superiores rapidamente.
cpp
void renderPathBar() {
auto relativePath = std::filesystem::relative(m_currentDirectory, m_rootPath);
std::string pathStr = relativePath.string();
// Divide pathStr por '/' e cria botões para cada segmento
// Ex: Assets > Textures > Player
}
Tipos de Ficheiro Suportados (M1)#
- Cenas:
.caf— Abre a cena no editor. - Texturas:
.png,.jpg,.tga— Mostra preview e permite arrastar paraSpriteRenderer. - Áudio:
.wav,.mp3— Identificado mas sem preview no M1.
Decisões de Design#
| Decisão | Justificativa |
|---|---|
std::filesystem |
Biblioteca robusta e multiplataforma incluída no C++17. |
| Drag-and-Drop Payload | Utilizar o caminho do ficheiro como payload facilita a integração com o AssetManager. |
| Layout em Grelha (Columns) | Maximiza o uso do espaço horizontal, semelhante aos exploradores de ficheiros modernos. |
Critério de Aceitação#
- [ ] Lista todos os ficheiros e pastas no diretório do projeto.
- [ ] Permite entrar em pastas com duplo clique (ou clique no botão).
- [ ] Botão "Back" funciona para subir na hierarquia de pastas.
- [ ] Ficheiros podem ser "arrastados" (ImGui Drag-and-Drop).
- [ ] Identifica visualmente ficheiros
.caf(Cenas). - [ ] Botão de "Refresh" atualiza a lista de ficheiros se algo mudar no disco.
Dependências#
- Upstream:
docs/assets/asset-manager.md - Downstream:
1.6-scene-editor-orchestrator.md,1.3-inspector-panel.md
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Asset Manager | Sistema que carrega os ficheiros selecionados em memória. |
| ImGui Drag & Drop | API para transferência de dados entre janelas. |
Referências#
docs/assets/asset-manager.md— Como os assets são registados.- C++ std::filesystem — Documentação técnica da biblioteca de ficheiros.