Galacean File Browser

A utility library for browsing and reading files from the assets directory, and for generating a cross‑package source/type index from the Galacean engine submodule.

Features

• Read files from the assets directory
• List all files in a specific directory
• Supports nested directory structures
• File content caching for better performance
• Path normalization and security checks

Installation

npm install @galacean/file-browser

Usage

Reading Files

import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// Read single or multiple files (paths are relative to assets/)
const contents = await reader.read([
  'galacean.md',
  'docs/engine.md'
]);
console.log(contents);

Listing Files

import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// List all files in a directory
const files = reader.listFiles('docs');
console.log(files);

Get Full Document Path

import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// Get the full path of a document under assets/docs
const fullPath = reader.getFullDocPath('engine.md');
console.log(fullPath);

Directory Structure

The library expects an assets directory in your project root. Typical structure:

assets/
├── docs/                       # Topic documents (Markdown)
│   ├── doc-directory.md        # Human‑friendly docs index
│   └── tool-index.md           # Generated tool list (from src/tools/**)
├── packages/                   # Copied src/types from submodule packages/*
├── directory/
│   └── code-directory.json     # Generated code index (see below)
│   └── tool-directory.json     # Consolidated tool schema map: { [toolId]: JSONSchema }
└── galacean.md                 # Quick prompt/overview

About code-directory.json

assets/directory/code-directory.json is an auto‑generated index (map) with the shape:

{
  "animator": [
    {
      "declare": "./packages/core/types/animation/Animator.d.ts",
      "source": "./packages/core/src/animation/Animator.ts"
    }
  ],
  "spriterenderer": [
    {
      "declare": "./packages/core/types/2d/sprite/SpriteRenderer.d.ts",
      "source": "./packages/core/src/2d/sprite/SpriteRenderer.ts"
    }
  ]
}

• Keys are lowercased export names.
• Values are arrays of { declare, source }, each path is relative to assets/.

Submodule and Sync (Pre‑requisites)

This project depends on the Galacean engine as a Git submodule and the ability to build it before generating the code index.

1. Update or initialize submodules

git submodule update --init --recursive

2. Install and build the engine submodule (requires pnpm)

cd external/galacean-engine
pnpm i
pnpm run b:all
cd -

3. Sync packages and generate code index

npm run sync:engine

This will:

• Clean assets/packages/*
• Copy external/galacean-engine/packages/*/{src,types} into assets/packages/*/{src,types}
• Generate assets/directory/code-directory.json

Tools Metadata and Index

The src/tools/** folder contains tool definitions. Each tool exports a meta object (with toolId and description) and a payloadSchema (zod schema).

You can generate a tools index and the consolidated tool schema map:

npm run gen:tool-index

This generates:

• assets/docs/tool-index.md — a table of all tools (toolId | description).
• assets/directory/tool-directory.json — a single JSON file mapping toolId to its JSON Schema.

Programmatic APIs

This package exposes a few simple helpers for working with the assets tree and the generated code index. The code index (assets/directory/code-directory.json) is read once and cached internally.

• readDocumentFiles(paths: string[]) → Promise<string[]>

  • Reads document files under assets/docs/. Each input is a file name like engine.md and the function will prefix ./docs/ automatically.
  • Example:

    import { readDocumentFiles } from '@galacean/file-browser';
    const docs = await readDocumentFiles(['engine.md', 'scene.md']);

• readDeclareFiles(names: string[]) → Promise<string[]>

  • Given export names (e.g., Animator), returns the corresponding declaration file contents (*.d.ts) via the code‑directory map.

• readSourceFiles(names: string[]) → Promise<string[]>

  • Given export names, returns the corresponding TypeScript source file contents.

• readToolFiles(names: string[]) → Promise<string[]>

  • Reads tool JSON Schemas from the consolidated map assets/directory/tool-directory.json generated by npm run gen:tool-index.
  • Each input is a toolId like asset.delete and the function returns the JSON string for that schema (empty string when missing).
  • Example:

    import { readToolFiles } from '@galacean/file-browser';
    const [schemaOrJson] = await readToolFiles(['asset.delete']);
    const schema = typeof schemaOrJson === 'string' ? JSON.parse(schemaOrJson) : schemaOrJson;

License

MIT