{"id":32868230,"url":"https://github.com/dhaniverse/texforge","last_synced_at":"2026-05-03T11:34:05.745Z","repository":{"id":323191661,"uuid":"1092420490","full_name":"dhaniverse/texforge","owner":"dhaniverse","description":"Forge textures for the GPU age. Convert PNG/JPG to KTX2 with blazing fast compression. 90% smaller files, hardware-accelerated loading for Phaser, Three.js, and Babylon.js.","archived":false,"fork":false,"pushed_at":"2025-11-08T17:10:39.000Z","size":5381,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-08T18:11:12.065Z","etag":null,"topics":["babylonjs","basis-uni","etc1s","game-development","gpu-compression","image-optimization","ktx2","performance","phaser","texture-compression","threejs","typescript","uastc","webgl","webgpu"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhaniverse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T15:45:03.000Z","updated_at":"2025-11-08T17:10:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dhaniverse/texforge","commit_stats":null,"previous_names":["dhaniverse/texforge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dhaniverse/texforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhaniverse%2Ftexforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhaniverse%2Ftexforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhaniverse%2Ftexforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhaniverse%2Ftexforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhaniverse","download_url":"https://codeload.github.com/dhaniverse/texforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhaniverse%2Ftexforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32567417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babylonjs","basis-uni","etc1s","game-development","gpu-compression","image-optimization","ktx2","performance","phaser","texture-compression","threejs","typescript","uastc","webgl","webgpu"],"created_at":"2025-11-09T08:00:42.941Z","updated_at":"2026-05-03T11:34:05.727Z","avatar_url":"https://github.com/dhaniverse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# texforge\n\nForge textures for the GPU age. Convert large images and texture atlases to GPU-optimized KTX2 format with automatic chunking and hardware-accelerated compression.\n\n## Features\n\n- **Automatic Image Chunking**: Split large maps into optimal chunks for streaming\n- **GPU-Native Compression**: Convert to KTX2 with ETC1S or UASTC compression\n- **90% Smaller Files**: Dramatically reduce texture memory and load times\n- **Phaser Integration**: Drop-in loader for Phaser 3.70+\n- **CLI and API**: Use as command-line tool or Node.js library\n- **Zero Configuration**: Works out of the box with sensible defaults\n\n## Installation\n\n```bash\nnpm install texforge\n```\n\n### Requirements\n\ntexforge requires `toktx` from KTX-Software:\n\n- **Windows**: Download from [KTX-Software releases](https://github.com/KhronosGroup/KTX-Software/releases)\n- **macOS**: `brew install ktx`\n- **Linux**: Download from KTX-Software releases\n\nVerify installation:\n```bash\ntexforge check\n```\n\n## Quick Start\n\n### One-Line Map Optimization\n\n```typescript\nimport { TexForge } from 'texforge';\n\nconst result = await TexForge.processMapToKTX2({\n  input: './my-huge-map.png',\n  outputDir: './public/maps',\n  chunkSize: 1024,\n  mode: 'etc1s'\n});\n\nconsole.log(`Saved ${result.totalSaved} bytes (${result.compressionRatio}% reduction)`);\n```\n\n### CLI Usage\n\n```bash\n# Convert single image\ntexforge convert image.png -o output.ktx2\n\n# Convert directory\ntexforge convert ./textures/ -o ./output/ --mode uastc\n\n# Process large map with chunking\ntexforge convert huge-map.png -o ./chunks/ --chunk-size 1024\n```\n\n## API Documentation\n\n### TexForge.processMapToKTX2(options)\n\nMain method that chunks a large image and converts all chunks to KTX2.\n\n```typescript\ninterface ProcessOptions {\n  input: string;              // Input image path\n  outputDir: string;          // Output directory for chunks\n  chunkSize?: number;         // Chunk size in pixels (default: 1024)\n  mode?: 'etc1s' | 'uastc';  // Compression mode (default: 'etc1s')\n  quality?: number;           // Quality 1-255 (default: 128)\n  compressionLevel?: number;  // Level 0-5 (default: 2)\n  mipmaps?: boolean;          // Generate mipmaps (default: false)\n}\n```\n\n**Returns**: `ProcessResult` with metadata, conversion stats, and file sizes.\n\n### ImageChunker\n\nSplit large images into chunks for streaming:\n\n```typescript\nimport { ImageChunker } from 'texforge';\n\nconst chunker = new ImageChunker({\n  chunkSize: 1024,\n  outputDir: './chunks',\n  format: 'png'\n});\n\nconst metadata = await chunker.chunkImage('./large-map.png');\n```\n\n### TextureForge\n\nConvert individual images to KTX2:\n\n```typescript\nimport { TextureForge } from 'texforge';\n\nconst forge = new TextureForge({\n  mode: 'etc1s',\n  quality: 128,\n  compressionLevel: 2\n});\n\nconst result = await forge.convertFile('./texture.png', './texture.ktx2');\n```\n\n### Phaser Integration\n\nLoad chunked KTX2 maps in Phaser:\n\n```typescript\nimport { PhaserKTX2Loader } from 'texforge';\n\nclass GameScene extends Phaser.Scene {\n  private loader: PhaserKTX2Loader;\n\n  async create() {\n    this.loader = new PhaserKTX2Loader(this, '/maps/chunks/');\n    \n    await this.loader.loadMetadata('/maps/chunks/metadata.json');\n    \n    // Load chunks around player position\n    this.loader.loadChunksInArea(playerX, playerY, 2);\n  }\n\n  update() {\n    // Dynamically load chunks as player moves\n    this.loader.loadChunksInArea(player.x, player.y, 2);\n  }\n}\n```\n\n## Compression Modes\n\n### ETC1S (Recommended)\n\n- **Best compression ratio**: 70-90% smaller than PNG\n- **Universal support**: Works on all devices\n- **Use for**: Large texture atlases, background images, UI textures\n\n```typescript\nmode: 'etc1s',\nquality: 128,           // Higher = better quality (1-255)\ncompressionLevel: 2     // Higher = smaller file (0-5)\n```\n\n### UASTC\n\n- **Higher quality**: Better visual fidelity\n- **Faster transcoding**: Hardware decode on GPU\n- **Use for**: Normal maps, detail textures, hero assets\n\n```typescript\nmode: 'uastc',\nquality: 2              // Quality level for UASTC\n```\n\n## Performance Benchmarks\n\nReal-world results from a 12000x8000px game map:\n\n| Format | Size | Load Time | Memory |\n|--------|------|-----------|--------|\n| PNG | 45 MB | 2.3s | 384 MB |\n| KTX2 (etc1s) | 4.2 MB | 0.3s | 48 MB |\n| Improvement | **90% smaller** | **87% faster** | **87% less** |\n\n## Complete Example: Dhaniverse Integration\n\n```typescript\n// Step 1: Process your map during build\nimport { TexForge } from 'texforge';\n\nawait TexForge.processMapToKTX2({\n  input: './assets/world-map.png',\n  outputDir: './public/maps',\n  chunkSize: 1024,\n  mode: 'etc1s',\n  quality: 128\n});\n\n// Step 2: Load in Phaser\nimport { PhaserKTX2Loader } from 'texforge';\n\nexport class MainScene extends Phaser.Scene {\n  private mapLoader: PhaserKTX2Loader;\n\n  async preload() {\n    this.mapLoader = new PhaserKTX2Loader(this);\n    const metadata = await this.mapLoader.loadMetadata('/maps/metadata.json');\n    \n    console.log(`Map size: ${metadata.totalWidth}x${metadata.totalHeight}`);\n    console.log(`Chunks: ${metadata.chunksX}x${metadata.chunksY}`);\n  }\n\n  create() {\n    // Load initial visible chunks\n    const player = this.add.sprite(100, 100, 'player');\n    this.mapLoader.loadChunksInArea(player.x, player.y, 3);\n  }\n\n  update() {\n    // Stream chunks as player moves\n    const player = this.physics.world.bounds;\n    this.mapLoader.loadChunksInArea(player.centerX, player.centerY, 2);\n  }\n}\n```\n\n## CLI Reference\n\n```bash\n# Convert with custom quality\ntexforge convert input.png --quality 200 --compression 4\n\n# UASTC mode for high-quality textures\ntexforge convert normal-map.png --mode uastc --normal-map\n\n# Generate mipmaps\ntexforge convert texture.png --mipmaps\n\n# Batch convert directory\ntexforge convert ./textures/ -o ./output/\n\n# Check installation\ntexforge check\n```\n\n## TypeScript Support\n\nFull TypeScript definitions included:\n\n```typescript\nimport type {\n  ChunkMetadata,\n  ChunkedMapMetadata,\n  ConversionOptions,\n  ConversionResult\n} from 'texforge';\n```\n\n## License\n\nMIT - Gursimran Singh\n\n## Credits\n\nBuilt with:\n- [KTX-Software](https://github.com/KhronosGroup/KTX-Software) - Khronos Group\n- [Sharp](https://sharp.pixelplumbing.com/) - Image processing\n- [Basis Universal](https://github.com/BinomialLLC/basis_universal) - GPU texture compression\n\n## Contributing\n\nIssues and PRs welcome at [github.com/dhaniverse/texforge](https://github.com/dhaniverse/texforge)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhaniverse%2Ftexforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhaniverse%2Ftexforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhaniverse%2Ftexforge/lists"}