{"id":47966517,"url":"https://github.com/web3dev1337/hytopia-map-compression","last_synced_at":"2026-04-04T10:36:03.646Z","repository":{"id":310300650,"uuid":"1039377238","full_name":"web3dev1337/hytopia-map-compression","owner":"web3dev1337","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-22T23:52:34.000Z","size":316,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-23T04:28:20.964Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/web3dev1337.png","metadata":{"files":{"readme":"README-ADVANCED.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-17T04:55:17.000Z","updated_at":"2026-02-22T23:48:22.000Z","dependencies_parsed_at":"2025-08-17T07:05:33.232Z","dependency_job_id":"b9c6e6d9-4843-4670-95ad-650dcd869ca4","html_url":"https://github.com/web3dev1337/hytopia-map-compression","commit_stats":null,"previous_names":["web3dev1337/hytopia-map-compression"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/web3dev1337/hytopia-map-compression","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-map-compression","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-map-compression/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-map-compression/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-map-compression/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/web3dev1337","download_url":"https://codeload.github.com/web3dev1337/hytopia-map-compression/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-map-compression/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"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":[],"created_at":"2026-04-04T10:36:03.565Z","updated_at":"2026-04-04T10:36:03.638Z","avatar_url":"https://github.com/web3dev1337.png","language":"TypeScript","readme":"# Hytopia Map Compression - Advanced Guide\n\nThis guide covers the advanced chunk loading system that achieves 97% performance improvement.\n\n## Chunk Loading System\n\nThe plugin includes a powerful chunk loading system that bypasses Hytopia's public API for ultra-fast map loading.\n\n### How DirectChunkLoaderV3 Works\n\nInstead of using `world.setBlock()` (which is slow), the plugin directly manipulates Hytopia's internal `chunkLattice` structure:\n\n```typescript\n// Traditional approach (SLOW - 1800ms for 23k blocks)\nfor (const [coord, blockId] of Object.entries(blocks)) {\n  const [x, y, z] = coord.split(',').map(Number);\n  world.setBlock(x, y, z, blockId);\n}\n\n// DirectChunkLoaderV3 approach (FAST - 55ms for 23k blocks)\nconst chunk = {\n  _blocks: typedBlockArray,\n  _originCoordinate: origin,\n  blocks: typedBlockArray,\n  originCoordinate: origin,\n  getBlockId: function(localCoord) {\n    const index = localCoord.x + (localCoord.y \u003c\u003c 4) + (localCoord.z \u003c\u003c 8);\n    return this._blocks[index];\n  }\n};\nchunkLattice._chunks.set(chunkKey, chunk);\n```\n\n## Precomputing Chunks\n\nFor maximum performance, generate chunks at build time:\n\n### Using the CLI Tool\n\n```bash\n# Install dependencies\ncd hytopia-map-compression\nnpm install\n\n# Generate JSON chunks (Brotli-compressed JSON, HyFire8 compatible)\nnpm run precompute assets/map.json assets/map.chunks\n\n# Generate binary chunks (custom ultra-fast format)\nnpm run precompute assets/map.json assets/map.chunks.bin -- --format=binary\n\n# Verify the output\nnpm run precompute assets/map.json assets/map.chunks -- --verify\n```\n\n### Programmatic API\n\n```typescript\nimport { PrecomputeChunks } from 'hytopia-map-compression/tools';\n\n// Generate JSON chunks\nawait PrecomputeChunks.precomputeFromMapFile('map.json', 'map.chunks');\n\n// Generate binary chunks\nawait PrecomputeChunks.createBinaryChunks('map.json', 'map.bin');\n\n// Load precomputed chunks\nconst world = await PrecomputeChunks.loadPrecomputedChunks('map.chunks');\n```\n\n## Chunk Formats\n\n### JSON Chunks Format\nBrotli-compressed JSON (compatible with HyFire8) that expands to:\n```json\n{\n  \"version\": 1,\n  \"chunkSize\": 16,\n  \"chunks\": [\n    {\n      \"origin\": { \"x\": 0, \"y\": 0, \"z\": 0 },\n      \"blocks\": [/* Uint8Array of 4096 blocks */]\n    }\n  ],\n  \"metadata\": {\n    \"totalBlocks\": 23867,\n    \"totalChunks\": 32,\n    \"bounds\": { /* min/max coordinates */ },\n    \"createdAt\": \"2024-01-01T00:00:00Z\",\n    \"sourceHash\": \"a1b2c3d4\"\n  }\n}\n```\n\n### Binary Chunks Format (v1)\nCustom format optimized for speed:\n```\n[magic:u32][chunkCount:u32]\nrepeat chunkCount:\n  [chunkX:i32][chunkY:i32][chunkZ:i32][blockCount:u32]\n  repeat blockCount:\n    [blockX:i32][blockY:i32][blockZ:i32][blockId:u16]\n```\n\n## Integration Examples\n\n### Basic Setup\n\n```typescript\nimport { MapCompression } from 'hytopia-map-compression';\n\nstartServer(async world =\u003e {\n  const mapCompressor = new MapCompression(world, {\n    format: 'chunks',\n    optimization: {\n      precompute: true,\n      enableChunking: true\n    }\n  });\n  \n  // This will use DirectChunkLoaderV3 internally\n  await mapCompressor.loadCompressed('assets/map.chunks');\n});\n```\n\n### Advanced Configuration\n\n```typescript\nconst mapCompressor = new MapCompression(world, {\n  format: 'binary',\n  debug: false,\n  metrics: true,\n  optimization: {\n    batchSize: 50000,\n    enableChunking: true,\n    precompute: true\n  }\n});\n\n// Load binary chunks\nawait mapCompressor.loadCompressed('assets/map.bin');\n\n// Get performance metrics\nconst metrics = mapCompressor.getMetrics();\nconsole.log(`Loaded ${metrics.blocksLoaded} blocks in ${metrics.loadTimeMs}ms`);\n```\n\n## Performance Benchmarks\n\nTesting with CS:GO Dust2 map (23,867 blocks):\n\n| Method | Load Time | Details |\n|--------|-----------|---------|\n| world.setBlock() loop | 1847ms | Traditional approach |\n| DirectChunkLoader (v1) | 600-1100ms | Batched setBlock calls |\n| DirectChunkLoaderV3 | **55ms** | Direct chunkLattice manipulation |\n| Binary Chunks | **40ms** | Optimized binary format |\n\n### Breakdown of 55ms Load Time\n- File read: 5ms\n- Decompression: 12ms\n- Chunk creation: 20ms\n- ChunkLattice injection: 17ms\n- Event emission: 1ms\n\n## Troubleshooting\n\n### Chunks Not Loading?\n\n1. **Check Hytopia version**: Requires 0.6.0+\n2. **Verify world.chunkLattice exists**:\n```typescript\nif (!world.chunkLattice) {\n  console.error('ChunkLattice not available');\n}\n```\n\n3. **Enable debug mode**:\n```typescript\nconst mc = new MapCompression(world, { debug: true });\n```\n\n### Performance Not Improving?\n\n1. **Ensure chunks are precomputed**: Check for `.chunks` or `.bin` files\n2. **Verify DirectChunkLoaderV3 is used**: Look for `[DirectChunkLoaderV3]` in logs\n3. **Check for other plugins**: Some plugins may interfere with chunk loading\n\n### Memory Issues?\n\n1. **Reduce batch size**:\n```typescript\noptimization: { batchSize: 10000 }\n```\n\n2. **Use binary format**: More memory efficient than JSON\n3. **Load chunks progressively**: Split large maps into regions\n\n## Internal Architecture\n\n### Class Hierarchy\n```\nMapCompression\n├── DirectChunkLoaderV3 (fast path)\n├── DirectChunkLoader (fallback)\n├── VarintCodec\n├── DeltaEncoder\n└── PrecomputeChunks (build tool)\n```\n\n### Loading Flow\n```\nloadCompressed()\n├── Detect format (json/varint/chunks/binary)\n├── If chunks: Use DirectChunkLoaderV3\n│   ├── Parse chunk data\n│   ├── Create chunk objects\n│   └── Inject into chunkLattice\n└── If compressed: Decompress then chunk load\n```\n\n## Contributing\n\nWhen contributing chunk loading improvements:\n\n1. **Benchmark before/after**: Use the included benchmark tools\n2. **Test with large maps**: Ensure scalability\n3. **Maintain compatibility**: Don't break existing formats\n4. **Document internals**: Update this guide with changes\n\n## Advanced Tips\n\n### Conditional Chunk Loading\n```typescript\n// Only load chunks within view distance\nconst viewDistance = 5; // chunks\nfor (const chunk of chunks) {\n  if (isWithinDistance(chunk, playerPos, viewDistance)) {\n    loader.loadChunk(chunk);\n  }\n}\n```\n\n### Dynamic Chunk Generation\n```typescript\n// Generate chunks on-the-fly for procedural maps\nconst chunk = generateProceduralChunk(x, z);\nloader.injectChunk(chunk);\n```\n\n### Chunk Streaming\n```typescript\n// Stream chunks from server\nconst stream = await fetch('/api/chunks/stream');\nconst reader = stream.body.getReader();\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  loader.loadChunkFromBuffer(value);\n}\n```\n\n## References\n\n- HyFire8 implementation: Original chunk loading approach\n- Hytopia SDK internals: ChunkLattice structure\n- Minecraft chunk format: Inspiration for 16x16x16 chunks\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dev1337%2Fhytopia-map-compression","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweb3dev1337%2Fhytopia-map-compression","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dev1337%2Fhytopia-map-compression/lists"}