# jameskmonger/317refactor architecture

> Architecture diagram of the GitHub repository jameskmonger/317refactor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jameskmonger/317refactor
- Repository: https://github.com/jameskmonger/317refactor

## Overview

##### Project Type and Purpose
- This is a standalone game‐client monolith (Java), specifically a refactored RuneScape 317 client for educational purposes.
- Its primary responsibility is to run the game loop: load resources, handle input, process game logic, render graphics, play audio, and communicate with a server.

##### High‐Level Architecture Analysis
- Top‐level “src/com/jagex/runescape” contains core game classes (Client, RSApplet, RSFrame).
- Subpackages break out subsystems:
- audio – sound generation and filtering
- bzip2 – data decompression
- collection – custom data structures and caches
- definition – game‐asset metadata (items, objects, animations)
- isaac – random number generator for packet obfuscation
- scene – world‐model and tile/objects spatial data
- screen – UI layers (title, game screen, minimap)
- sign – networking helper (signlink, RSSocket, OnDemandFetcher)
- docs/tile_rendering.md gives insight into tile rendering logic.

##### Key Components
a. Game Client Core
- RSApplet/RSFrame: windowing and bootstrapping
- Client.java: main game loop (tick, render, update)
b. Input Handling
- MouseDetection, TextInput, TextClass
c. Networking & Data Fetching
- signlink.java, RSSocket, OnDemandFetcher, OnDemandData, PacketInformation
- ISAACRandomGenerator: packet stream encryption/decryption
d. Resource Management
- Archive, FileCache, Buffer, bzip2 Decompressor, IndexedImage, Sprite
- collection.Cache, CacheableQueue for in‐memory asset caches
e. Game World & Logic
- WorldController, Region, CollisionMap, GameObject, NPC, Player, Projectile
- definition.*: metadata loaders for entities, animations, maps
f. Rendering Engine
- Rasterizer, DrawingArea, TiledUtils, Model/ModelHeader, VertexNormal
- scene.tile and scene.object classes
g. UI / Screen Layers
- RSInterface, TitleScreen, FlameColours, Minimap
h. Audio Subsystem
- Instrument, Effect, SoundFilter, Envelope

##### Relationships and Data Flows
- On start, RSApplet → Client.main initializes signlink, caching, resource archives.
- Client enters game loop:
1. Input Handling → updates input state
2. Game Logic (Client) → uses definitions, world state, collision maps to update entities
3. Networking → send/receive packets via RSSocket; pack/unpack with ISAAC
4. Resource Manager → fetch missing assets on demand (OnDemandFetcher) → decompress with Bzip2 → cache
5. Rendering → Rasterizer and DrawingArea render tiles, models, UI
6. Audio → generate sounds per game events via audio subsystem
- Subsystems talk to central caches (collection.Cache) and archives.

##### Architectural Patterns and Principles
- Modular subsystems organized by feature (rendering, audio, networking).
- Custom caching layer to manage memory usage.
- Single‐threaded game loop driving all subsystems.
- Data‐driven definitions for game assets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Game Client
    subgraph "Core Game Client"
        direction TB
        RSApplet["RSApplet"]:::core
        RSFrame["RSFrame"]:::core
        Client["Client"]:::core
    end

    %% Main Game Loop
    GameLoop(("Game Loop")):::core

    %% Input Handling
    subgraph "Input Handling"
        direction TB
        Mouse["MouseDetection"]:::input
        TextIn["TextInput"]:::input
        TextClass["TextClass"]:::input
    end

    %% Game Logic & World
    subgraph "Game World & Logic"
        direction TB
        WorldCtrl["WorldController"]:::logic
        Region["Region"]:::logic
        Collision["CollisionMap"]:::logic
        GameObj["GameObject"]:::logic
        NPC["NPC"]:::logic
        Player["Player"]:::logic
        Projectile["Projectile"]:::logic
        Definitions["definition/*"]:::logic
    end

    %% Networking & Security
    subgraph "Networking & Data Fetching"
        direction TB
        Signlink["signlink"]:::network
        RSSocket["RSSocket"]:::network
        PacketInfo["PacketInformation"]:::network
        ISAAC["ISAACRandomGenerator"]:::network
        OnDemandFetcher["OnDemandFetcher"]:::network
        OnDemandData["OnDemandData"]:::network
    end

    %% Resource Management & Caching
    subgraph "Resource Management & Caching"
        direction TB
        Archive["Archive"]:::resource
        FileCache["FileCache"]:::resource
        Buffer["Buffer"]:::resource
        Bzip2["Bzip2Decompressor"]:::resource
        Bzip2State["Bzip2DecompressionState"]:::resource
        IndexedImage["IndexedImage"]:::resource
        Sprite["Sprite"]:::resource
        Cache["Cache"]:::resource
        Queue["CacheableQueue"]:::resource
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        direction TB
        Raster["Rasterizer"]:::render
        DrawArea["DrawingArea"]:::render
        TiledUtils["TiledUtils"]:::render
        Model["Model"]:::render
        ModelHdr["ModelHeader"]:::render
        Vertex["VertexNormal"]:::render
        TilePkg["scene/tile/*"]:::render
        ObjPkg["scene/object/*"]:::render
    end

    %% UI / Screen Layers
    subgraph "UI / Screen Layers"
        direction TB
        RSInterface["RSInterface"]:::ui
        Title["TitleScreen"]:::ui
        Flame["FlameColours"]:::ui
        Minimap["Minimap"]:::ui
    end

    %% Audio Subsystem
    subgraph "Audio Subsystem"
        direction TB
        Instrument["Instrument"]:::audio
        Effect["Effect"]:::audio
        Envelope["Envelope"]:::audio
        SoundFilter["SoundFilter"]:::audio
    end

    %% Flow
    RSApplet --> Client
    RSFrame --> Client
    Client --> GameLoop
    GameLoop -->|User Events| Mouse
    GameLoop -->|User Events| TextIn
    GameLoop -->|User Events| TextClass
    GameLoop -->|Update Logic| WorldCtrl
    GameLoop --> Region
    GameLoop --> Collision
    GameLoop --> GameObj
    GameLoop --> NPC
    GameLoop --> Player
    GameLoop --> Projectile
    GameLoop --> Definitions
    GameLoop <-->|Packet In/Out| Signlink
    Signlink --> RSSocket
    RSSocket --> ISAAC
    Signlink --> OnDemandFetcher
    OnDemandFetcher --> OnDemandData
    OnDemandFetcher --> Bzip2
    Bzip2 --> Bzip2State
    OnDemandData --> Archive
    Archive --> FileCache
    Archive --> Buffer
    FileCache --> Cache
    FileCache --> Queue
    GameLoop --> Raster
    Raster --> DrawArea
    DrawArea --> TiledUtils
    DrawArea --> Model
    DrawArea --> ModelHdr
    DrawArea --> Vertex
    DrawArea --> TilePkg
    DrawArea --> ObjPkg
    GameLoop --> RSInterface
    RSInterface --> Title
    RSInterface --> Flame
    RSInterface --> Minimap
    GameLoop --> Instrument
    GameLoop --> Effect
    Effect --> Envelope
    Effect --> SoundFilter

    %% Click Events
    click Client "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Client.java"
    click RSApplet "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/RSApplet.java"
    click RSFrame "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/RSFrame.java"
    click Mouse "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/MouseDetection.java"
    click TextIn "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/TextInput.java"
    click TextClass "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/TextClass.java"
    click Signlink "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/sign/signlink.java"
    click RSSocket "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/RSSocket.java"
    click OnDemandFetcher "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/OnDemandFetcher.java"
    click OnDemandData "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/OnDemandData.java"
    click PacketInfo "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/PacketInformation.java"
    click ISAAC "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/isaac/ISAACRandomGenerator.java"
    click Archive "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Archive.java"
    click FileCache "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/FileCache.java"
    click Buffer "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Buffer.java"
    click Bzip2 "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/bzip2/Bzip2Decompressor.java"
    click Bzip2State "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/bzip2/Bzip2DecompressionState.java"
    click IndexedImage "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/IndexedImage.java"
    click Sprite "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Sprite.java"
    click Cache "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/collection/Cache.java"
    click Queue "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/collection/CacheableQueue.java"
    click WorldCtrl "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/scene/WorldController.java"
    click Region "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Region.java"
    click Collision "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/CollisionMap.java"
    click GameObj "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/GameObject.java"
    click NPC "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/NPC.java"
    click Player "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Player.java"
    click Projectile "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Projectile.java"
    click Definitions "https://github.com/jameskmonger/317refactor/tree/master/src/com/jagex/runescape/definition/"
    click Raster "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Rasterizer.java"
    click DrawArea "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/DrawingArea.java"
    click TiledUtils "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/TiledUtils.java"
    click Model "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/Model.java"
    click ModelHdr "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/ModelHeader.java"
    click Vertex "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/VertexNormal.java"
    click TilePkg "https://github.com/jameskmonger/317refactor/tree/master/src/com/jagex/runescape/scene/tile/"
    click ObjPkg "https://github.com/jameskmonger/317refactor/tree/master/src/com/jagex/runescape/scene/object/"
    click RSInterface "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/RSInterface.java"
    click Title "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/screen/title/TitleScreen.java"
    click Flame "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/screen/title/FlameColours.java"
    click Minimap "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/screen/game/Minimap.java"
    click Instrument "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/audio/Instrument.java"
    click Effect "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/audio/Effect.java"
    click Envelope "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/audio/Envelope.java"
    click SoundFilter "https://github.com/jameskmonger/317refactor/blob/master/src/com/jagex/runescape/audio/SoundFilter.java"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,stroke-width:1px
    classDef input fill:#E6FFE6,stroke:#28a745,stroke-width:1px
    classDef logic fill:#E6E6E6,stroke:#6c757d,stroke-width:1px
    classDef network fill:#FFF4E6,stroke:#d9730d,stroke-width:1px
    classDef resource fill:#E6FFE6,stroke:#2c6f2e,stroke-width:1px
    classDef render fill:#F0E6FF,stroke:#6f42c1,stroke-width:1px
    classDef ui fill:#F2F2F2,stroke:#adb5bd,stroke-width:1px
    classDef audio fill:#FFF9E6,stroke:#d39e00,stroke-width:1px
```
