# bnanz0/ok-duet-night-abyss architecture

> Architecture diagram of the GitHub repository bnanz0/ok-duet-night-abyss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bnanz0/ok-duet-night-abyss
- Repository: https://github.com/bnanz0/ok-duet-night-abyss

## Overview

1. **Overall purpose**
   - This repository is a Windows-based Python automation tool for the game *Duet Night Abyss*.
   - It does not inject into the game; the automation loop works by reading screen/UI state and sending simulated input, including support for background operation.

2. **Core architecture style**
   - The code is organized around a **task-driven automation engine**.
   - High-level tasks decide what to do next, while lower-level modules provide scene recognition, combat checks, character interaction, and input-triggered behaviors.
   - The design is modular enough to support built-in automation and externally packaged “Mod” logic.

3. **Entry points and runtime**
   - `main.py` is the normal launcher; `main_debug.py` is the verbose/debug launcher.
   - The project targets **Python 3.12** on **Windows**, and the README indicates the game should run at 1600×900 or higher for reliable image matching.
   - Packaging and distribution are supported through GitHub releases and PyAppify-related configuration.

4. **Task orchestration layer**
   - `src/tasks` is the main orchestration boundary.
   - It contains specialized automation flows such as:
     - general automation and exploration
     - escort, fishing, excavation, expulsion, defense, hedge, skill use
     - commission handling and one-time DNA tasks
   - Subpackages split execution styles:
     - `fullauto` for end-to-end autonomous loops
     - `trigger` for reactive, condition-driven behaviors
   - This is the primary place where the bot decides “what mode am I in?” and “what sequence should run now?”

5. **Base task abstractions**
   - Shared task behavior appears to live in:
     - `BaseCombatTask`
     - `BaseDNATask`
     - `BaseListenerTask`
   - These likely define lifecycle, polling, state transitions, and the integration points between detection, combat, and input handling.
   - `CommissionsTask`, `DNAOneTimeTask`, and similar classes are concrete flows built on those base abstractions.

6. **Scene recognition and state detection**
   - `src/scene/DNAScene.py` is the most explicit scene module and likely encapsulates UI/state recognition for the game.
   - `assets/coco_annotations.json` and the image assets indicate an **image-recognition pipeline** driven by reference screenshots or annotations.
   - `src/process_feature.py` and `src/globals.py` suggest shared feature extraction / state context used across tasks.

7. **Combat and character domain**
   - `src/combat/CombatCheck.py` handles combat-state detection or readiness checks.
   - `src/char/BaseChar.py` suggests character-specific logic, likely abstracting skills, actions, or character capabilities.
   - `src/LabelEnum.py` probably centralizes recognition labels used by detection and decision-making code.

8. **Configuration and task parameters**
   - `src/config.py` is the global configuration boundary.
   - Task-specific configuration is separated under `src/tasks/config`, including commission and skill-related settings.
   - This separation implies the runtime behavior is shaped by user-facing configuration rather than hardcoded mode-specific values.

9. **Mod/extensibility model**
   - The `mod` directory is a first-class extension mechanism.
   - It includes built-in path definitions such as `escort_paths.json` and `puzzle_paths.json`, plus example community content with scripts and map assets.
   - The README confirms users can drop external mods into `mod/` and restart to load them, so the architecture explicitly supports pluggable automation logic and custom recognition materials.

10. **Internationalization and assets**
   - The `i18n` directory contains compiled and source message catalogs for multiple locales: English, Chinese, Japanese, Korean, Spanish, and Traditional Chinese.
   - This suggests the UI or logs are localized, while the automation logic remains language-aware through these catalogs.
   - `assets/images`, icons, and annotation files are part of the recognition and packaging pipeline.

11. **Testing and validation**
   - `tests/TestMissonInterface.py` and `tests/images` indicate automated validation around mission/UI recognition.
   - The presence of GitHub workflows for build, test, stale cleanup, and release notes implies CI is used to verify packaging and basic behavior.

12. **Important architectural boundary**
   - The main boundary in this repo is between:
     - **screen/state understanding** via image recognition and scene checks
     - **decision logic** in tasks and triggers
     - **action execution** via simulated inputs and background-compatible interaction
   - For an architecture diagram, the central flow is: game screen → recognition/state modules → task/trigger logic → input/output actions → back to game screen, with `mod/` and configuration altering the behavior of that loop.

Main entry points: [`src/tasks/AutoGeneral.py`](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoGeneral.py) (General Auto), [`src/tasks/trigger`](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/src/tasks/trigger) (Triggers), [`src/scene/DNAScene.py`](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/scene/DNAScene.py) (DNA Scene), [`src/tasks/BaseDNATask.py`](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/BaseDNATask.py) (Base Tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_main_debug_py["main_debug.py<br/>entrypoint<br/>[main_debug.py]"]
end

subgraph group_automation["Automation Core"]
  node_auto_general["General Auto<br/>task orchestration<br/>[AutoGeneral.py]"]
  node_auto_exploration["Exploration<br/>task orchestration<br/>[AutoExploration.py]"]
  node_auto_defence["Defense<br/>task orchestration<br/>[AutoDefence.py]"]
  node_auto_excavation["Excavation<br/>task orchestration<br/>[AutoExcavation.py]"]
  node_auto_expulsion["Expulsion<br/>task orchestration<br/>[AutoExpulsion.py]"]
  node_auto_hedge["Hedge<br/>task orchestration<br/>[AutoHedge.py]"]
  node_auto_skill["Skill Use<br/>task orchestration<br/>[AutoSkill.py]"]
  node_commissions_task["Commissions<br/>task flow<br/>[CommissionsTask.py]"]
  node_dna_one_time["DNA One-Time<br/>task flow<br/>[DNAOneTimeTask.py]"]
  node_fullauto_bundle["Full Auto<br/>full-auto flows"]
  node_trigger_bundle["Triggers<br/>reactive tasks"]
  node_base_tasks["Base Tasks<br/>task abstractions<br/>[BaseDNATask.py]"]
end

subgraph group_perception["Perception & State"]
  node_dna_scene["DNA Scene<br/>scene recognition<br/>[DNAScene.py]"]
  node_combat_check["Combat Check<br/>combat detection<br/>[CombatCheck.py]"]
  node_state_core(("State Core<br/>shared context<br/>[globals.py]"))
  node_base_char["Base Char<br/>character domain<br/>[BaseChar.py]"]
end

subgraph group_extension["Extensions & Assets"]
  node_mod_dir["mods<br/>extension packs"]
  node_assets[("Assets")]
  node_i18n["i18n<br/>localization"]
end

subgraph group_quality["Quality & Delivery"]
  node_tests["Tests<br/>validation"]
  node_ci_cd["CI/CD<br/>automation pipeline<br/>[workflows]"]
end

node_main_py -->|"launches"| node_auto_general
node_main_debug_py -->|"launches"| node_auto_general
node_auto_general -->|"extends"| node_base_tasks
node_base_tasks -->|"specializes"| node_commissions_task
node_base_tasks -->|"specializes"| node_dna_one_time
node_auto_general -->|"routes"| node_auto_exploration
node_auto_general -->|"routes"| node_auto_defence
node_auto_general -->|"routes"| node_auto_excavation
node_auto_general -->|"routes"| node_auto_expulsion
node_auto_general -->|"routes"| node_auto_hedge
node_auto_general -->|"routes"| node_auto_skill
node_auto_general -->|"routes"| node_commissions_task
node_auto_general -->|"routes"| node_dna_one_time
node_auto_general -->|"routes"| node_fullauto_bundle
node_auto_general -->|"routes"| node_trigger_bundle
node_trigger_bundle -->|"depends on"| node_combat_check
node_trigger_bundle -->|"uses"| node_base_char
node_auto_general -->|"reads"| node_dna_scene
node_dna_scene -->|"shares state"| node_state_core
node_combat_check -->|"shares state"| node_state_core
node_auto_general -->|"matches against"| node_assets
node_dna_scene -->|"matches against"| node_assets
node_mod_dir -->|"extends"| node_fullauto_bundle
node_mod_dir -->|"extends"| node_trigger_bundle
node_i18n -->|"localizes"| node_auto_general
node_tests -->|"validates"| node_dna_scene
node_ci_cd -->|"runs"| node_tests

click node_main_py "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/main.py"
click node_main_debug_py "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/main_debug.py"
click node_auto_general "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoGeneral.py"
click node_auto_exploration "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExploration.py"
click node_auto_defence "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoDefence.py"
click node_auto_excavation "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExcavation.py"
click node_auto_expulsion "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExpulsion.py"
click node_auto_hedge "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoHedge.py"
click node_auto_skill "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoSkill.py"
click node_commissions_task "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/CommissionsTask.py"
click node_dna_one_time "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/DNAOneTimeTask.py"
click node_fullauto_bundle "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/src/tasks/fullauto"
click node_trigger_bundle "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/src/tasks/trigger"
click node_base_tasks "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/BaseDNATask.py"
click node_dna_scene "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/scene/DNAScene.py"
click node_combat_check "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/combat/CombatCheck.py"
click node_state_core "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/globals.py"
click node_base_char "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/char/BaseChar.py"
click node_mod_dir "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/mod"
click node_assets "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/assets"
click node_i18n "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/i18n"
click node_tests "https://github.com/bnanz0/ok-duet-night-abyss/tree/master/tests"
click node_ci_cd "https://github.com/bnanz0/ok-duet-night-abyss/blob/master/.github/workflows"

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_main_py,node_main_debug_py toneBlue
class node_auto_general,node_auto_exploration,node_auto_defence,node_auto_excavation,node_auto_expulsion,node_auto_hedge,node_auto_skill,node_commissions_task,node_dna_one_time,node_fullauto_bundle,node_trigger_bundle,node_base_tasks toneAmber
class node_dna_scene,node_combat_check,node_state_core,node_base_char toneMint
class node_mod_dir,node_assets,node_i18n toneRose
class node_tests,node_ci_cd toneIndigo
```

## Components

### Runtime

Launchers and packaging entrypoints

- [main.py](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/main.py): entrypoint · Normal application launcher · `main.py`
- [main_debug.py](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/main_debug.py): entrypoint · Verbose/debug launcher · `main_debug.py`

### Automation Core

Task orchestration and execution modes

- [General Auto](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoGeneral.py): task orchestration · Top-level automation mode selection and loop control · `src/tasks/AutoGeneral.py`
- [Exploration](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExploration.py): task orchestration · Free-roam and navigation automation · `src/tasks/AutoExploration.py`
- [Defense](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoDefence.py): task orchestration · Defense mission automation · `src/tasks/AutoDefence.py`
- [Excavation](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExcavation.py): task orchestration · Excavation mission automation · `src/tasks/AutoExcavation.py`
- [Expulsion](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoExpulsion.py): task orchestration · Expulsion mission automation · `src/tasks/AutoExpulsion.py`
- [Hedge](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoHedge.py): task orchestration · Hedge mission automation · `src/tasks/AutoHedge.py`
- [Skill Use](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/AutoSkill.py): task orchestration · Skill-triggered automation flow · `src/tasks/AutoSkill.py`
- [Commissions](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/CommissionsTask.py): task flow · Commission handling workflow built on base task logic · `src/tasks/CommissionsTask.py`
- [DNA One-Time](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/DNAOneTimeTask.py): task flow · One-shot automation flow for specific runs · `src/tasks/DNAOneTimeTask.py`
- [Full Auto](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/src/tasks/fullauto): full-auto flows · End-to-end autonomous task variants and packaged flows · `src/tasks/fullauto`
- [Triggers](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/src/tasks/trigger): reactive tasks · Condition-driven listeners and in-combat helpers · `src/tasks/trigger`
- [Base Tasks](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/tasks/BaseDNATask.py): task abstractions · Shared lifecycle and state-machine foundations for automation tasks · `src/tasks/BaseDNATask.py`

### Perception & State

Scene recognition, combat checks, and shared game state

- [DNA Scene](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/scene/DNAScene.py): scene recognition · Game scene and UI state recognition · `src/scene/DNAScene.py`
- [Combat Check](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/combat/CombatCheck.py): combat detection · Combat-state and readiness detection · `src/combat/CombatCheck.py`
- [State Core](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/globals.py): shared context · Shared globals, feature extraction, and label vocabulary · `src/globals.py`
- [Base Char](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/src/char/BaseChar.py): character domain · Character capability abstraction used by combat and action logic · `src/char/BaseChar.py`

### Extensions & Assets

Mods, localization, and recognition assets

- [mods](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/mod): extension packs · Pluggable external scripts, paths, and example content · `mod`
- [Assets](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/assets): recognition assets · Reference images and annotation data for screen matching · `assets`
- [i18n](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/i18n): localization · Compiled and source translation catalogs · `i18n`

### Quality & Delivery

Tests and CI/CD

- [Tests](https://github.com/bnanz0/ok-duet-night-abyss/tree/master/tests): validation · UI/mission recognition checks and image fixtures · `tests`
- [CI/CD](https://github.com/bnanz0/ok-duet-night-abyss/blob/master/.github/workflows): automation pipeline · GitHub workflows for build, test, and release tasks · `.github/workflows`

## Connections

- main.py → General Auto: launches · Starts the normal automation runtime
- main_debug.py → General Auto: launches · Starts the verbose/debug runtime
- General Auto → Base Tasks: extends · Uses shared task lifecycle and state handling
- Base Tasks → Commissions: specializes · Concrete workflow built on base task abstractions
- Base Tasks → DNA One-Time: specializes · Concrete workflow built on base task abstractions
- General Auto → Exploration: routes · Selects exploration mode when roaming/navigation is needed
- General Auto → Defense: routes · Selects defense mission mode
- General Auto → Excavation: routes · Selects excavation mission mode
- General Auto → Expulsion: routes · Selects expulsion mission mode
- General Auto → Hedge: routes · Selects hedge mission mode
- General Auto → Skill Use: routes · Selects skill-driven automation mode
- General Auto → Commissions: routes · Selects commission workflow
- General Auto → DNA One-Time: routes · Selects one-time DNA workflow
- General Auto → Full Auto: routes · Selects end-to-end autonomous variants
- General Auto → Triggers: routes · Selects reactive trigger-driven helpers
- Triggers → Combat Check: depends on · Triggers react to combat and engagement state
- Triggers → Base Char: uses · Character-specific behavior and action handling
- General Auto → DNA Scene: reads · Decision-making depends on scene/UI recognition
- DNA Scene → State Core: shares state · Scene recognition contributes to shared state context
- Combat Check → State Core: shares state · Combat checks consume shared state and labels
- General Auto → Assets: matches against · Uses image templates and annotations for recognition
- DNA Scene → Assets: matches against · Scene detection is driven by reference assets
- mods → Full Auto: extends · Mods provide extra paths and scripted automation content
- mods → Triggers: extends · Mods can add reactive logic or path data
- i18n → General Auto: localizes · Provides translated UI/log strings for runtime
- Tests → DNA Scene: validates · Mission/UI recognition is exercised by tests
- CI/CD → Tests: runs · Workflow executes tests and packaging checks