ARCHITECTURE.md - SYSTEM ARCHITECTURE & TECHNICAL CORE

Tämä dokumentti määrittelee The Chronicles of Ultimate Retro Station -projektin teknisen rakenteen, emuloitavat alustat ja ohjelmistokerrokset.

---

1. LAITEARKKITEHTUURI (HARDWARE STACK)

Järjestelmä on rakennettu modifioidun Nintendo Wii -konsolin ympärille, joka toimii isäntänä (Host) useille emulaatiokerroksille.

Kerros	Komponentti / Teknologia
Isäntäkone	Nintendo Wii (RVL-001)
Prosessori	IBM Broadway (PowerPC 750CL) @ 729 MHz
Grafiikka	ATI Hollywood GPU @ 243 MHz
Tallennus	250GB SSD (External USB via Custom Interface)
Kotelo	WII-64 CHASSIS Custom Mod
Verkko	Local / Crypto-secured Node

---

2. JÄRJESTELMÄHISTORIA (1977 - 2006)

Järjestelmä on konfiguroitu tukemaan seuraavia laitteistoarkkitehtuureja kronologisessa järjestyksessä:

Vuosi	Laite	Valmistaja	Arkkitehtuuri
1977	Apple II	Apple	8-bit
1977	Commodore PET	Commodore	8-bit
1979	Atari 800	Atari	8-bit
1980	Commodore VIC-20	Commodore	8-bit
1982	Commodore 64	Commodore	8-bit
1982	Sinclair ZX Spectrum	Sinclair	8-bit
1983	Nintendo NES	Nintendo	8-bit
1983	MSX Standard	Various	8-bit
1984	Amstrad CPC	Amstrad	8-bit
1984	Commodore Plus/4	Commodore	8-bit
1985	Commodore Amiga 500	Commodore	16/32-bit
1985	Commodore 128	Commodore	8/16-bit
1988	SEGA Mega Drive	SEGA	16-bit
1990	Nintendo SNES	Nintendo	16-bit
1994	Sony PlayStation	Sony	32-bit
1996	Nintendo 64	Nintendo	64-bit
2001	Nintendo GameCube	Nintendo	Native/HW
2006	Nintendo Wii (Host)	Nintendo	PowerPC

---

3. OHJELMISTOKERROKSET (SOFTWARE STACK)

Emulaatio ja natiiviajo on jaettu kolmeen pääkerrokseen:

A. Kernel & Boot

• IOS/cIOS: Custom IOS -rajapinnat (d2x) mahdollistavat SSD-yhteyden ja lukunopeuden optimoinnin.
• Priiloader: Suojaus "brickaantumista" vastaan ja suora käynnistys kustomoituihin lataajiin.

B. Loaders & Engines

• USB Loader GX: Ensisijainen käyttöliittymä Wii- ja GameCube-peleille.
• Nintendont: Natiivitasoinen GameCube-moottori, joka mahdollistaa SSD-tuen ja ohjainmuunnokset.
• Dolphin SDK Integrations: Kehitystyökalut koodin kääntämiseen ja testaukseen.

C. Emulation Cores

• RetroArch: Universaali rajapinta 8-bit ja 16-bit järjestelmille.
• WiiStation: Optimoitu MIPS-arkkitehtuurin (PS1) tulkki.
• UAE4Wii: Erillinen moottori Amiga-arkkitehtuurin emulointiin.

---

4. TEKNISET HAVAINNOT JA OPTIMOINTI

• Audio: Alkuperäiset äänipiirit (esim. SID, Paula) emuloidaan DSP-tasolla latenssin minimoimiseksi.
• Video: Järjestelmä suosii 240p-natiiviulostuloa analogisen signaalin kautta CRT-yhteensopivuuden varmistamiseksi.
• Input: HID-yhteensopivuus mahdollistaa nykyaikaisten ohjainten käytön klassisissa ympäristöissä.

---

Wii‑kehityksen teknologiakartta

Tämä dokumentti kuvaa keskeiset työkalut, kirjastot ja työnkulun, joita tarvitaan Nintendo Wiille kehitettävän oman ohjelmiston (Homebrew) tekemiseen.

---

Technology Layers

graph TD
    subgraph "1. Development Environment"
        A[VS Code / IDE] -->|Write C/C++| B(Source Code)
        B --> C{devkitPPC}
        D[libogc / GRRLIB] --> C
        C -->|Compile| E[Game Binary .dol]
    end

    subgraph "2. Testing"
        E --> F[Dolphin Emulator]
        F -->|Debug| A
    end

    subgraph "3. Assets"
        G[Blender / GIMP] --> H[Raw Assets]
        H --> I[Converters]
        I -->|Headers| B
    end

    subgraph "4. Real Wii"
        E --> J{Wiiload}
        J --> K[Homebrew Channel]
        K --> L[Wii Hardware]
        M[Wiimote] -->|Input| L
    end

    %% Värien määrittely (varmista yhteensopivuus)
    style A fill:#3b3f5c,stroke:#ccc,stroke-width:2px
    style E fill:#4e5d94,stroke:#ccc,stroke-width:4px
    style F fill:#3a6ea5,stroke:#ccc,stroke-width:2px
    style L fill:#5c5c3d,stroke:#ccc,stroke-width:2px

---

LAYER 1: Hardware (Wii Console)

The physical foundation your code interacts with. * CPU: IBM PowerPC "Broadway" (729 MHz). * GPU: ATI "Hollywood" (243 MHz). * RAM: 24 MB (MEM1) + 64 MB (MEM2). Memory management is critical! * Input: Bluetooth (Wiimote), IR Sensor, Accelerometers.

LAYER 2: Toolchain & Low-Level

Tools that translate your code into Wii-compatible machine language. * devkitPPC: The C/C++ compiler (part of the devkitPro suite). * libogc: The essential low-level library. It’s the open-source alternative to Nintendo's official SDK, managing controllers, memory, and filesystem. * Makefile: Instructions for the compiler on how to build and link your project.

LAYER 3: Graphics & APIs (Libraries)

High-level abstractions to simplify development. * GRRLIB: The most popular 2D/3D library for hobbyists. It simplifies texture loading and rendering. * GX: Wii’s native low-level graphics API (similar to OpenGL). GRRLIB runs on top of this. * ASND / AESND: Libraries for audio and music playback. * Fatfs: Library for reading/writing data to the SD card.

LAYER 4: Environment & Testing (Workflow)

Where you write code and how you run it. * Editor: Visual Studio Code (recommended) or Code::Blocks. * Dolphin Emulator: The gold standard for testing. Use this for 99% of development. * Homebrew Channel: Required on a physical Wii to run your custom code. * Wiiload: A utility to send your compiled game from PC to Wii over the network.

LAYER 5: Asset Pipeline

Games need visuals and sound. * Blender: For 3D modeling. * GIMP / Photoshop: For texture creation. * PNG2TPL / ImageMagick: Tools to convert standard images into Wii-native formats (TPL). * Audacity: For converting audio to PCM or OGG formats.

---