# marcosvll2/neoxtractor architecture

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

- Interactive diagram: https://gitdiagram.com/marcosvll2/neoxtractor
- Repository: https://github.com/marcosvll2/neoxtractor

## Overview

NeoXtractor is a GUI-first tool for opening NPK archives, optionally applying game-specific configuration, browsing and filtering entries, then extracting or previewing them. The archive readers parse indexes and decode entry data; format processors and specialized viewers support richer previews, including mesh and texture assets. The README documents config selection, archive loading, filtering, extraction, renaming, and viewer selection. Several viewer and reader internals were not sampled, so their links are omitted unless supported by the README or SOURCE INDEX.

Main entry points: [`gui/windows/main_window.py`](https://github.com/marcosvll2/neoxtractor/blob/main/gui/windows/main_window.py) (Main window), [`core/npk/npk_file.py`](https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/npk_file.py) (NPK reader), [`gui/widgets/viewers`](https://github.com/marcosvll2/neoxtractor/tree/main/gui/widgets/viewers) (Specialized viewers), [`core/wpk/wpk_file.py`](https://github.com/marcosvll2/neoxtractor/blob/main/core/wpk/wpk_file.py) (WPK reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_entrypoint["App entrypoint<br/>[main.py]"]
  node_main_window["Main window<br/>[main_window.py]"]
  node_file_list["Archive file list<br/>[npk_file_list.py]"]
  node_filter["Entry filter"]
  node_preview["Preview panel<br/>[preview_widget.py]"]
  node_viewer_dispatch["Viewer selection<br/>[viewer.py]"]
  node_special_viewers["Specialized viewers"]
end

subgraph group_archive["Archive Reading"]
  node_npk_reader["NPK reader<br/>[npk_file.py]"]
  node_wpk_reader["WPK reader<br/>[wpk_file.py]"]
  node_entry_model["Entry data model<br/>[class_types.py]"]
  node_binary_readers["Binary primitives<br/>[binary_readers.py]"]
  node_export["Entry export<br/>[class_types.py]"]
end

subgraph group_assets["Asset Processing"]
  node_format_processors["Format processors<br/>[registry.py]"]
  node_image_support["Image handling<br/>[images.py]"]
  node_mesh_loader["Mesh loading<br/>[new_parser.py]"]
  node_mesh_renderer["Mesh rendering<br/>[mesh_renderer.py]"]
  node_cocos_viewer["Cocos viewer<br/>[cocos_viewer.py]"]
end

subgraph group_settings["Configuration"]
  node_config_ui["Config manager UI"]
  node_config_manager["Game configs<br/>[config_manager.py]"]
  node_config_model["Config model<br/>[config.py]"]
  node_settings["GUI settings"]
end

node_user(("User"))

node_user -->|"starts"| node_entrypoint
node_entrypoint -->|"starts GUI"| node_main_window
node_user -->|"opens archive"| node_main_window
node_main_window -->|"loads NPK"| node_npk_reader
node_main_window -->|"loads WPK"| node_wpk_reader
node_npk_reader -->|"reads fields"| node_binary_readers
node_npk_reader -->|"creates entries"| node_entry_model
node_wpk_reader -->|"creates entries"| node_entry_model
node_npk_reader -->|"processes entries"| node_format_processors
node_wpk_reader -->|"processes entries"| node_format_processors
node_main_window -->|"shows entries"| node_file_list
node_main_window -->|"filters entries"| node_filter
node_main_window -->|"previews selection"| node_preview
node_preview -->|"selects viewer"| node_viewer_dispatch
node_viewer_dispatch -->|"registers viewers"| node_special_viewers
node_user -->|"requests extraction"| node_export
node_main_window -->|"extracts entries"| node_export
node_format_processors -.->|"decodes images"| node_image_support
node_special_viewers -->|"loads mesh data"| node_mesh_loader
node_mesh_renderer -->|"renders loaded mesh"| node_mesh_loader
node_special_viewers -->|"includes viewer"| node_cocos_viewer
node_user -->|"manages configs"| node_config_ui
node_config_ui -->|"updates configs"| node_config_manager
node_config_manager -->|"loads config files"| node_config_model
node_main_window -->|"selects active config"| node_config_manager
node_main_window -->|"uses settings"| node_settings

click node_entrypoint "https://github.com/marcosvll2/neoxtractor/blob/main/main.py"
click node_main_window "https://github.com/marcosvll2/neoxtractor/blob/main/gui/windows/main_window.py"
click node_file_list "https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/npk_file_list.py"
click node_filter "https://github.com/marcosvll2/neoxtractor/blob/main/gui/npk_entry_filter.py"
click node_preview "https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/preview_widget.py"
click node_viewer_dispatch "https://github.com/marcosvll2/neoxtractor/blob/main/gui/utils/viewer.py"
click node_special_viewers "https://github.com/marcosvll2/neoxtractor/tree/main/gui/widgets/viewers"
click node_npk_reader "https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/npk_file.py"
click node_wpk_reader "https://github.com/marcosvll2/neoxtractor/blob/main/core/wpk/wpk_file.py"
click node_entry_model "https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/class_types.py"
click node_binary_readers "https://github.com/marcosvll2/neoxtractor/blob/main/core/binary_readers.py"
click node_format_processors "https://github.com/marcosvll2/neoxtractor/blob/main/core/formats/registry.py"
click node_image_support "https://github.com/marcosvll2/neoxtractor/blob/main/core/images.py"
click node_mesh_loader "https://github.com/marcosvll2/neoxtractor/blob/main/core/mesh_loader/parsers/new_parser.py"
click node_mesh_renderer "https://github.com/marcosvll2/neoxtractor/blob/main/gui/renderers/mesh_renderer.py"
click node_cocos_viewer "https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/viewers/cocos_viewer/cocos_viewer.py"
click node_config_ui "https://github.com/marcosvll2/neoxtractor/blob/main/gui/windows/config_manager/config_manager_window.py"
click node_config_manager "https://github.com/marcosvll2/neoxtractor/blob/main/gui/config_manager.py"
click node_config_model "https://github.com/marcosvll2/neoxtractor/blob/main/core/config.py"
click node_settings "https://github.com/marcosvll2/neoxtractor/blob/main/gui/settings_manager.py"
click node_export "https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/class_types.py"

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_entrypoint,node_main_window,node_file_list,node_filter,node_preview,node_viewer_dispatch,node_special_viewers,node_user toneBlue
class node_npk_reader,node_wpk_reader,node_entry_model,node_binary_readers,node_export toneAmber
class node_format_processors,node_image_support,node_mesh_loader,node_mesh_renderer,node_cocos_viewer toneMint
class node_config_ui,node_config_manager,node_config_model,node_settings toneRose
```

## Components

### Application UI

- [App entrypoint](https://github.com/marcosvll2/neoxtractor/blob/main/main.py): `main.py`
- [Main window](https://github.com/marcosvll2/neoxtractor/blob/main/gui/windows/main_window.py): `gui/windows/main_window.py`
- [Archive file list](https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/npk_file_list.py): `gui/widgets/npk_file_list.py`
- [Entry filter](https://github.com/marcosvll2/neoxtractor/blob/main/gui/npk_entry_filter.py): `gui/npk_entry_filter.py`
- [Preview panel](https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/preview_widget.py): `gui/widgets/preview_widget.py`
- [Viewer selection](https://github.com/marcosvll2/neoxtractor/blob/main/gui/utils/viewer.py): `gui/utils/viewer.py`
- [Specialized viewers](https://github.com/marcosvll2/neoxtractor/tree/main/gui/widgets/viewers): `gui/widgets/viewers`

### Archive Reading

- [NPK reader](https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/npk_file.py): `core/npk/npk_file.py`
- [WPK reader](https://github.com/marcosvll2/neoxtractor/blob/main/core/wpk/wpk_file.py): `core/wpk/wpk_file.py`
- [Entry data model](https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/class_types.py): `core/npk/class_types.py`
- [Binary primitives](https://github.com/marcosvll2/neoxtractor/blob/main/core/binary_readers.py): `core/binary_readers.py`
- [Entry export](https://github.com/marcosvll2/neoxtractor/blob/main/core/npk/class_types.py): `core/npk/class_types.py`

### Asset Processing

- [Format processors](https://github.com/marcosvll2/neoxtractor/blob/main/core/formats/registry.py): `core/formats/registry.py`
- [Image handling](https://github.com/marcosvll2/neoxtractor/blob/main/core/images.py): `core/images.py`
- [Mesh loading](https://github.com/marcosvll2/neoxtractor/blob/main/core/mesh_loader/parsers/new_parser.py): `core/mesh_loader/parsers/new_parser.py`
- [Mesh rendering](https://github.com/marcosvll2/neoxtractor/blob/main/gui/renderers/mesh_renderer.py): `gui/renderers/mesh_renderer.py`
- [Cocos viewer](https://github.com/marcosvll2/neoxtractor/blob/main/gui/widgets/viewers/cocos_viewer/cocos_viewer.py): `gui/widgets/viewers/cocos_viewer/cocos_viewer.py`

### Configuration

- [Config manager UI](https://github.com/marcosvll2/neoxtractor/blob/main/gui/windows/config_manager/config_manager_window.py): `gui/windows/config_manager/config_manager_window.py`
- [Game configs](https://github.com/marcosvll2/neoxtractor/blob/main/gui/config_manager.py): `gui/config_manager.py`
- [Config model](https://github.com/marcosvll2/neoxtractor/blob/main/core/config.py): `core/config.py`
- [GUI settings](https://github.com/marcosvll2/neoxtractor/blob/main/gui/settings_manager.py): `gui/settings_manager.py`

### Other components

- **User**

## Connections

- User → App entrypoint: starts
- App entrypoint → Main window: starts GUI (evidence: `main.py`)
- User → Main window: opens archive
- Main window → NPK reader: loads NPK (evidence: `gui/windows/main_window.py`)
- Main window → WPK reader: loads WPK (evidence: `gui/windows/main_window.py`)
- NPK reader → Binary primitives: reads fields (evidence: `core/npk/npk_file.py`)
- NPK reader → Entry data model: creates entries (evidence: `core/npk/npk_file.py`)
- WPK reader → Entry data model: creates entries (evidence: `core/wpk/wpk_file.py`)
- NPK reader → Format processors: processes entries (evidence: `core/npk/npk_file.py`)
- WPK reader → Format processors: processes entries (evidence: `core/wpk/wpk_file.py`)
- Main window → Archive file list: shows entries (evidence: `gui/windows/main_window.py`)
- Main window → Entry filter: filters entries (evidence: `gui/windows/main_window.py`)
- Main window → Preview panel: previews selection (evidence: `gui/windows/main_window.py`)
- Preview panel → Viewer selection: selects viewer (evidence: `gui/widgets/preview_widget.py`)
- Viewer selection → Specialized viewers: registers viewers (evidence: `gui/utils/viewer.py`)
- User → Entry export: requests extraction
- Main window → Entry export: extracts entries (evidence: `gui/windows/main_window.py`)
- Format processors → Image handling: decodes images
- Specialized viewers → Mesh loading: loads mesh data
- Mesh rendering → Mesh loading: renders loaded mesh (evidence: `gui/renderers/mesh_renderer.py`)
- Specialized viewers → Cocos viewer: includes viewer (evidence: `gui/utils/viewer.py`)
- User → Config manager UI: manages configs
- Config manager UI → Game configs: updates configs (evidence: `gui/windows/config_manager/config_manager_window.py`)
- Game configs → Config model: loads config files (evidence: `gui/config_manager.py`)
- Main window → Game configs: selects active config (evidence: `gui/windows/main_window.py`)
- Main window → GUI settings: uses settings (evidence: `gui/windows/main_window.py`)
