RS-Cache

An immutable, high-level API for the RuneScape cache file system.

This crate provides convenient access to the binary file system of the Oldschool RuneScape and RuneScape 3 caches.

The library's API is mainly focussed around reading bytes easily. Therefore it offers a higher level of abstraction then most other libraries. Most cache API's expose a wide variety of internal types to let the user tinker around with the cache in unusual ways. To avoid undefined behavior most internal types are kept private. The goal of this crate is to provide a simple interface for basic reading of valuable data.

Note that this crate is still evolving, both OSRS & RS3 are not fully supported/implemented and will probably contain bugs or miss vital features. If this is the case for you then consider opening an issue.

Useful links:
        Releases
        Documentation
        Examples

Safety

This crate internally uses memmap and this is safe because: the RuneScape cache is a read-only binary files ystem which is never modified by any process, and should never be modified. To ensure the main file is never moved while the cache has memory mapped to it a file handle is kept internally to make access more safe. It is not possible to prevent parallel access to a certain file and prevent modifications. Therefore file-backed mapped memory is inherently unsafe.

Features

The cache's protocol defaults to OSRS. In order to use the RS3 protocol you can enable the rs3 feature flag. A lot of types derive serde's Serialize and Deserialize. To enable (de)serialization on most types use the serde-derive feature flag.

Quick Start

use rscache::Cache;

fn main() -> rscache::Result<()> {
    let cache = Cache::new("./data/osrs_cache")?;

    let index_id = 2; // Config index.
    let archive_id = 10; // Archive containing item definitions.

    let buffer: Vec<u8> = cache.read(index_id, archive_id)?;

    Ok(())
}

The osrs specifications and rs3 specifications documents contain a detailed description of the design of the corresponding cache for educational purposes. Both documents are still a work in progress and are possibly incomplete.

Integration tests are running on Oldschool RuneScape version 180, which you can run at any time because the cache is included in the ./data/osrs_cache directory. RS3 Integration tests are running on version 904. The RS3 cache is too large to include on GitHub.

This crate is experimentald. I will implement Additional features once I need them for my own project. If you require a certain feature feel free to open an issue.

Usage

Add this to your Cargo.toml:

[dependencies]
rs-cache = "0.7"

Examples can be found in the examples directory.

Acknowledgements

The following sources aided with the development of this crate:
        OpenRS
        RuneLite
        OSRS Cache Parsing Blog
        RSMod
        Librsfs
        OSRSBox
        Jagex-Store-5
        Matrix 876

License

RS-Cache is distributed under the terms of the MIT license.

See LICENSE for details.