BYML Lens

[English] | 简体中文

BYML Lens is an Antigravity/VS Code extension specifically designed for high-frequency editing and auditing of BYML, SARC, and Zstandard (.zs) compressed files. It provides a lightning-fast and seamless asset editing experience by transparently mapping binary files to native text views.

Core Features

• 🚀 Click-to-Edit: Automatically intercepts .byml, .bgyml, and .pack.zs binary files, instantly converting them into highlighted YAML text.
• 🧬 Auto-Embedded Metadata: YAML output now includes version, endianness, and precise type maps in a header document, enabling reference-free recompilation.
• 📦 SARC Virtualization: Double-click any .pack archive to mount it as a virtual directory. Add, modify, or delete internal files as if they were in a normal folder.
• ⚡️ Transparent Zstd Support: All read and write operations automatically detect and handle Zstandard compression. No manual decompression or re-compression required.
• 🎨 Visual Alias System: Use a byml-aliases.yml in your workspace root to dynamically replace cryptic codenames (e.g., Vss_AutoWalk00) with friendly names (e.g., Lemuria Hub). Aliases are automatically reverted upon saving to maintain data integrity.
• 💎 Native Integration: Fully compatible with editor themes. Supports line numbers, full-text search, multi-cursor editing, and indentation guides.

Usage

1. Command Line Interface (CLI)

For AI Agents and batch processing, you can use the byml-lens command:

# Install globally
npm install -g .

# Decompile BYML to YAML (Multi-document format with metadata)
byml-lens deyaml Versus.byml.zs result.yaml

# Recompile YAML to binary
# Automatically detects version/types from the YAML header - no --reference needed!
byml-lens yaml2byml result.yaml new_Versus.byml.zs

# Unpack SARC archive (Extract raw binary)
byml-lens unpack Versus.pack.zs ./out_folder

# Unpack and Decompile (Ideal for AI Agents)
byml-lens unpack Versus.pack.zs ./editable_folder --yaml

# Pack a directory into SARC (with auto-encoding)
byml-lens pack ./editable_folder new_archive.pack.zs --zstd --yaml

2. Editing BYML/BGYML in VS Code

• Edit: The file opens as a native YAML document with full syntax highlighting. The header contains _byml_metadata which preserves the binary technical standards.
• Save: Press Cmd+S (Mac) or Ctrl+S (Win). The extension automatically handles binary encoding and Zstd compression while maintaining hardware compatibility.

3. Mounting SARC (.pack)

• Mount: Double-click a .pack or .pack.zs file. A virtual directory named Archive: [filename] will appear in your workspace.
• Edit/Delete: You can modify files or delete entire folders (e.g. Banc) directly from the sidebar.
• Unmount: Double-click the same file again, or right-click the virtual folder and select "Unmount .pack Archive".

4. Custom Aliases

• Create byml-aliases.yml in your project root:

  Vss_AutoWalk00: Lemuria Hub
  Vss_BigSlope00: Brinewater Springs
  

• Re-open a BYML file to see the IDs automatically replaced with your custom names.

Development & Build

Recommended Development Workflow

For active development, use the built-in VS Code debugger:

1. Open the project in Antigravity or VS Code.
2. Press F5 to launch the "Extension Development Host".
3. This opens a new window with your latest code active, supporting breakpoints and live logs.

Build from Source

1. Clone and Install:

   git clone <repository_url>
   cd byml-vscode-extension
   make install
   

2. Package to VSIX:

   make package
   

3. Manual Install: In the Extensions view, click ... -> Install from VSIX... and select the generated file.

Troubleshooting & Feedback

If you encounter issues or corrupted files, please provide logs from the Output panel:

1. Open the Output panel (View -> Output).
2. Select BYML Lens from the dropdown menu in the top-right corner.
3. For deeper investigation, enable debug logs in settings: BYML Lens > Debug.
4. Copy the logs and attach them to your GitHub Issue.

Produced by space4 with 🩵