# thiagodnf/wumpus-world-simulator architecture

> Architecture diagram of the GitHub repository thiagodnf/wumpus-world-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiagodnf/wumpus-world-simulator
- Repository: https://github.com/thiagodnf/wumpus-world-simulator

## Overview

1. **Project shape**
   - This is a **browser-based, static JavaScript game**: `index.html` plus CSS, JS, images, audio, and translation files.
   - There is **no backend, database, or API layer** in the repository; all game state and behavior live client-side.

2. **Runtime boundary**
   - The app runs entirely in the **browser DOM**.
   - `index.html` is the entry point, which pulls in styling, scripts, and asset references needed to render and run the Wumpus World simulator.

3. **Primary UI layer**
   - `css/style.css` controls the visual layout and presentation.
   - `img/` contains UI assets, including favicon files and the screenshot used for project documentation.
   - The visual game board and interaction surfaces are likely rendered directly in the page rather than through a framework.

4. **Game orchestration**
   - `js/script.js` is the central application coordinator.
   - It likely wires together user input, game state updates, rendering, sound playback, and language selection.

5. **Core game model**
   - `js/core/environment.js` represents the Wumpus world state and rules: the cave/grid, hazards, and game conditions.
   - `js/core/player.js` models the player’s position, movement, and actions.
   - `js/core/keys.js` defines keyboard controls and input mapping.
   - `js/core/resources.js` manages loading and access to external assets such as audio and localized content.

6. **Utility layer**
   - `js/utils/random-utils.js` and `js/utils/array-utils.js` provide supporting logic used by the core game.
   - These helpers isolate reusable operations like random selection and array manipulation from the game rules.

7. **Localization subsystem**
   - `i18n/*.json` contains translation bundles for multiple locales: English, Portuguese, Arabic, French, Spanish, and Turkish.
   - This suggests the UI text is internationalized and selected dynamically at runtime, with language resources kept separate from the game code.

8. **Audio feedback**
   - `audio/` contains the game’s sound effects and music: movement, coins, errors, background audio, win, and game-over cues.
   - Audio is part of the interaction loop, providing immediate feedback for player actions and state changes.

9. **Data flow**
   - User input enters through browser events, especially keyboard input.
   - `script.js` routes those events into the core model (`environment`, `player`), which updates game state.
   - The updated state drives UI changes and triggers audio/resources as needed.

10. **Asset loading boundary**
   - Resource files are separate from logic, which makes the architecture easy to diagram as:
     - **static assets** (audio, images, i18n)
     - **presentation** (HTML/CSS)
     - **game logic** (core + utils + orchestrator)
   - `resources.js` is the likely boundary between code and asset management.

11. **Deployment model**
   - The README indicates the game is hosted on **GitHub Pages**, which fits the repository’s static-site structure.
   - That means the architecture is intended for simple client-side deployment with no server runtime.

12. **Important diagram takeaway**
   - The cleanest architecture diagram would show a **single browser application** with:
     - entry point: `index.html`
     - orchestrator: `js/script.js`
     - core domain modules: `js/core/*`
     - helpers: `js/utils/*`
     - localized text: `i18n/*`
     - media assets: `audio/*` and `img/*`
     - presentation: `css/style.css`

Main entry points: [`js/script.js`](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/script.js) (Game loop), [`js/core/environment.js`](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/environment.js) (Environment), [`js/core/resources.js`](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/resources.js) (Resources), [`index.html`](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/index.html) (index.html)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser app"]
  node_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_style_css["Style sheet<br/>presentation css<br/>[style.css]"]
  node_script_js["Game loop<br/>app orchestrator<br/>[script.js]"]
end

subgraph group_logic["Game logic"]
  node_environment_js["Environment<br/>world model<br/>[environment.js]"]
  node_player_js["Player<br/>actor model<br/>[player.js]"]
  node_keys_js["Key map<br/>input mapping<br/>[keys.js]"]
  node_resources_js["Resources<br/>asset loader<br/>[resources.js]"]
  node_random_utils_js["Random utils<br/>[random-utils.js]"]
  node_array_utils_js["Array utils<br/>[array-utils.js]"]
end

subgraph group_assets["Static assets"]
  node_i18n_bundle["Translations<br/>localization bundles<br/>[en_us.json]"]
  node_audio_assets["Audio<br/>sound effects<br/>[background.mp3]"]
  node_img_assets["Images<br/>ui assets<br/>[manifest.json]"]
end

node_index_html -->|"loads"| node_style_css
node_index_html -->|"boots"| node_script_js
node_script_js -->|"updates"| node_environment_js
node_script_js -->|"moves"| node_player_js
node_script_js -->|"reads input"| node_keys_js
node_script_js -->|"loads assets"| node_resources_js
node_script_js -->|"uses"| node_random_utils_js
node_script_js -->|"uses"| node_array_utils_js
node_script_js -->|"selects text"| node_i18n_bundle
node_script_js -->|"plays"| node_audio_assets
node_script_js -->|"renders assets"| node_img_assets
node_resources_js -->|"serves"| node_audio_assets
node_resources_js -->|"serves"| node_i18n_bundle
node_environment_js -->|"uses"| node_random_utils_js
node_environment_js -->|"uses"| node_array_utils_js
node_player_js -->|"interacts with"| node_environment_js

click node_index_html "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/index.html"
click node_style_css "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/css/style.css"
click node_script_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/script.js"
click node_environment_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/environment.js"
click node_player_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/player.js"
click node_keys_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/keys.js"
click node_resources_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/resources.js"
click node_random_utils_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/utils/random-utils.js"
click node_array_utils_js "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/utils/array-utils.js"
click node_i18n_bundle "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/i18n/en_us.json"
click node_audio_assets "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/audio/background.mp3"
click node_img_assets "https://github.com/thiagodnf/wumpus-world-simulator/blob/master/img/favicon/manifest.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_style_css,node_script_js toneBlue
class node_environment_js,node_player_js,node_keys_js,node_resources_js,node_random_utils_js,node_array_utils_js toneAmber
class node_i18n_bundle,node_audio_assets,node_img_assets toneMint
```

## Components

### Browser app

Client-side entry point, UI, and orchestration in the browser DOM.

- [index.html](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/index.html): entry page · Browser entry point that loads the game shell and scripts. · `index.html`
- [Style sheet](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/css/style.css): presentation css · Controls layout and visual presentation. · `css/style.css`
- [Game loop](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/script.js): app orchestrator · Main coordinator that wires input, state, rendering, audio, and language selection. · `js/script.js`

### Game logic

Core Wumpus World model, controls, and supporting utilities.

- [Environment](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/environment.js): world model · Represents cave state, hazards, and game rules. · `js/core/environment.js`
- [Player](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/player.js): actor model · Tracks player position, movement, and actions. · `js/core/player.js`
- [Key map](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/keys.js): input mapping · Defines keyboard controls and input bindings. · `js/core/keys.js`
- [Resources](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/core/resources.js): asset loader · Loads and exposes external assets such as audio and localized content. · `js/core/resources.js`
- [Random utils](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/utils/random-utils.js): utility · Reusable randomization helpers. · `js/utils/random-utils.js`
- [Array utils](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/js/utils/array-utils.js): utility · Reusable array manipulation helpers. · `js/utils/array-utils.js`

### Static assets

Localized text and media loaded by the browser game.

- [Translations](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/i18n/en_us.json): localization bundles · Locale-specific UI strings for multiple languages. · `i18n/en_us.json`
- [Audio](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/audio/background.mp3): sound effects · Movement, error, win, game-over, and background sounds. · `audio/background.mp3`
- [Images](https://github.com/thiagodnf/wumpus-world-simulator/blob/master/img/favicon/manifest.json): ui assets · Favicon and documentation imagery used by the static site. · `img/favicon/manifest.json`

## Connections

- index.html → Style sheet: loads · The page includes the stylesheet for the game UI.
- index.html → Game loop: boots · The page starts the browser game runtime.
- Game loop → Environment: updates · Coordinates world state and game rules.
- Game loop → Player: moves · Applies player actions and position changes.
- Game loop → Key map: reads input · Maps keyboard events to game actions.
- Game loop → Resources: loads assets · Uses the resource boundary for media and locale data.
- Game loop → Random utils: uses · Relies on helper logic for random behavior.
- Game loop → Array utils: uses · Relies on helper logic for array operations.
- Game loop → Translations: selects text · Chooses localized UI strings at runtime.
- Game loop → Audio: plays · Triggers sound feedback for actions and outcomes.
- Game loop → Images: renders assets · Uses static images and favicon assets in the UI.
- Resources → Audio: serves · Provides access to sound files.
- Resources → Translations: serves · Provides access to translation bundles.
- Environment → Random utils: uses · May use random helpers to build or vary the world.
- Environment → Array utils: uses · May use array helpers for grid or entity handling.
- Player → Environment: interacts with · Player actions depend on the current world state.
