Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (31 loc) · 4.85 KB

AGENTS.md

File metadata and controls

36 lines (31 loc) · 4.85 KB

Repository Guidelines

Project Structure & Module Organization

The CLI lives in src/main.rs with argument parsing in src/args.rs and data types in src/types.rs. Submodules under src/format, src/scripts, src/output_scripts, and src/utils hold codec implementations and shared helpers - mirror that layout when adding new game engines or formats. The procedural macro crate is in msg_tool_macro/; keep its API stable with the matching version declared in Cargo.toml. Sample game assets used for manual verification live under testscripts/, while patched reference outputs go in patched/ and scratch artifacts in output/. All scripts should implement the Script and ScriptBuilder trait in src/scripts/base.rs. New script's type should be registered in src/types.rs. The corresponding script builder should be registered in src/scripts/mod.rs. If new flag are added, please register them in src/args.rs and src/types.rs (ExtraConfig). Some useful utilities are in src/utils/. Some utilities should enabled via feature flags in Cargo.toml. If user give some example files in testscripts/. Run cargo run -- export <file> to test if export works.

Coding Style & Naming Conventions

Target the Rust 2024 edition with rustfmt defaults (4-space indentation, trailing commas). Modules and files stay in snake_case, public types in PascalCase, and flags/features use the hyphenated scheme already present (e.g., bgi-arc). Prefer explicit use blocks near call sites and annotate complex transforms with concise comments. Keep CLI option identifiers aligned with the conventions in src/args.rs. DO NOT USE ANY CODE CAN CAUSE PANIC IN LIBRARY CODE. panic only allowed in main.rs , args.rs and tests.

Core Utilities (src/utils/)

  • counter.rs - Thread-safe counters summarizing script outcomes; used to report OK/ignored/error/warning totals. Use crate::COUNTER to get global instance.
  • encoding.rs - Shared encode/decode helpers with BOM detection, replacement handling, and optional Kirikiri wrappers for MDF and SimpleCrypt payloads.
  • files.rs - Path utilities to collect inputs, filter by known script or archive extensions, stream stdin/stdout, and sanitize Windows file names.
  • struct_pack.rs - Traits plus blanket implementations for binary pack/unpack backed by the msg_tool_macro crate; used when codecs read or write structured data.
  • Feature-gated helpers such as bit_stream.rs or threadpool.rs stay under the same module; enable them via the matching utils-* features in Cargo.toml.

Command line tools

Use UNIX tools to list directory contents, search text, and compare files. For example: ls, find, grep. POWERHSELL COMMANDS ARE NOT ALLOWED.

IO Extensions (src/ext/io.rs)

For endian-aware operation, default to little-endian, unless _be suffix is used. _le suffix are not used in the code.

  • Peek (for Read + Seek) – adds non-destructive read helpers: generic peek/peek_at, typed endian-aware primitives (peek_u8…peek_i128_be), string readers (peek_cstring, peek_fstring, UTF-16 helpers), struct loaders via StructUnpack (read_struct, read_struct_vec), and assertions (peek_and_equal).
  • CPeek (thread-safe peek facade) – mirrors Peek on shared references with exact/offset variants, typed primitives, string helpers, and matchers; implemented for Mutex<T: Peek>, in-memory readers, and writers.
  • ReadExt (for Read) – provides endian-aware reads for integers/floats, C/fixed/UTF-16 string loaders using Encoding, vector reads (read_exact_vec), and equality assertions (read_and_equal).
  • WriteExt (for Write) – exposes endian-aware writers for integers, signed values, floats, C-strings, plus write_struct delegating to StructPack with encoding awareness.
  • WriteAt (for Write + Seek) – writes at absolute offsets with typed wrappers (write_u8_at…write_i128_be_at) and C-string support, restoring the original cursor after each call.
  • SeekExt (for Seek) – offers stream_length (length without disturbing position) and align (rounds the cursor up to a power-of-two boundary).
  • MemReader / MemReaderRef – byte-slice backed readers implementing Read, Seek, Peek, and CPeek; support cloning, EOF checks, borrowing via to_ref, and safe position management.
  • MemWriter – growable in-memory writer implementing Write, Seek, and CPeek; supports constructing from/into Vec<u8> and borrowing via to_ref.
  • StreamRegion<T: Seek> – wraps a stream segment with bounded Read/Seek, keeping track of local position and guarding seeks outside the declared range.
  • BinaryPatcher<R, W, A, O> – coordinates incremental patching by copying sections, mapping offsets between old/new layouts, replacing ranges with provided writers, and patching values/addresses through user-supplied address↔offset closures.