Skip to content

Commit cc26c52

Browse files
chripa85chripa85
committed
Initial public release of the accessibility mod
Summary: - add screen-reader-driven menu, settings, and gameplay accessibility support - add custom gameplay keybindings, map navigation, discovery helpers, bookmarks, and keep-site search - add stable logging for manual in-game verification - document controls, architecture, install, build, deploy, and regression testing guidance - keep local reverse-engineering material and generated output out of the public repository
0 parents  commit cc26c52

45 files changed

Lines changed: 10595 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 463 additions & 0 deletions
Large diffs are not rendered by default.

‎AGENTS.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
Core mod source lives in `src/kc-accessibility/` (C# .NET Framework 4.7.2 class library).
5+
Reference assemblies and native dependencies are in `lib/` (for example `Assembly-CSharp.dll`, `0Harmony.dll`, `Tolk.dll`).
6+
Generated/staged mod files are in `mod/kc-accessibility/` and should be treated as build output.
7+
Helper scripts are in `scripts/`:
8+
- `stage-mod.cmd` copies built artifacts and source payload into `mod/...`
9+
- `deploy-mod-to-game.cmd` copies the staged mod into the game install
10+
11+
Public documentation lives under `doc/`. Local-only research, decompiled references, and machine-specific notes belong under ignored `local/`.
12+
13+
## Build, Test, and Development Commands
14+
- `msbuild src\kc-accessibility\kc-accessibility.csproj /t:Build /p:Configuration=Debug`
15+
Builds the mod DLL and runs the post-build stage step.
16+
- `cmd /c scripts\stage-mod.cmd "C:\...\src\kc-accessibility\"`
17+
Manually refreshes `mod/kc-accessibility/`.
18+
- `cmd /c scripts\deploy-mod-to-game.cmd`
19+
Deploys staged files to the local game install configured by the script.
20+
21+
## Coding Style & Naming Conventions
22+
Use C# with 4-space indentation and braces on new lines (existing repository style).
23+
Prefer small, focused helper methods over long monolithic handlers.
24+
Use `PascalCase` for types/methods/properties, `camelCase` for fields/locals.
25+
Keep log messages explicit and stable for gameplay verification.
26+
27+
## Testing Guidelines
28+
There is currently no automated test project. Validate by:
29+
1. Building successfully.
30+
2. Deploying via script.
31+
3. Verifying behavior and logs in game (`output.txt` in mod folder and global `mods\log.txt`).
32+
33+
When changing input/navigation logic, include a short manual test note in PR/commit context.
34+
35+
## Commit & Pull Request Guidelines
36+
Recent commit history favors short imperative messages (for example: `Fix quit dialog navigation`, `Refactor accessibility code`).
37+
Keep commits scoped to one change area (bindings, gameplay navigation, menu handling, refactor).
38+
PRs should include:
39+
- what changed and why
40+
- affected game screens/states
41+
- verification steps performed
42+
- relevant log excerpts or screenshots when behavior changes
43+
44+
## Agent-Specific Instructions
45+
- You should not make manual changes to the `mod` folder. Whenever the stage script is executed the files in there are modified.
46+
- You should not change files deployed as this is done by the deploy script.

‎README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Kingdoms and Castles Accessibility Mod
2+
3+
Accessibility mod for *Kingdoms and Castles* focused on screen-reader support, spoken menu navigation, and keyboard-driven gameplay navigation.
4+
5+
## What It Does
6+
7+
The mod adds spoken feedback for:
8+
9+
- game load and save-load events
10+
- main menu and settings navigation
11+
- gameplay map navigation
12+
- building placement and build menu navigation
13+
- gameplay panel access such as island info, worker/job views, and related UI
14+
- island summaries, keep-relative navigation, resource announcements, and other accessibility-oriented helpers
15+
16+
Speech output is provided through Tolk, with direct NVDA fallback handling when needed.
17+
18+
## Requirements
19+
20+
- Windows version of *Kingdoms and Castles*
21+
- a working screen reader such as NVDA
22+
- the game's mod loading system enabled through the normal `mods` folder
23+
24+
## Install
25+
26+
Build the project or run the stage script, then copy the staged `mod/kc-accessibility/` folder into the game's `mods` directory so the final structure is:
27+
28+
```text
29+
KingdomsAndCastles_Data/
30+
mods/
31+
kc-accessibility/
32+
info.json
33+
ScreenReaderAccessibilityBehaviour.cs
34+
ScreenReaderLoadMod.cs
35+
keybindings.json
36+
Tolk.dll
37+
nvdaControllerClient64.dll
38+
...
39+
```
40+
41+
This mod is packaged as source files plus metadata and native speech DLLs, not as a single mod DLL. The native speech DLLs must remain beside the mod files.
42+
43+
## Build
44+
45+
Build the project from the repository root:
46+
47+
```powershell
48+
msbuild src\kc-accessibility\kc-accessibility.csproj /t:Build /p:Configuration=Debug
49+
```
50+
51+
The post-build step stages the mod into `mod/kc-accessibility/`.
52+
53+
## Deploy
54+
55+
Deploy the staged mod with:
56+
57+
```powershell
58+
cmd /c scripts\deploy-mod-to-game.cmd
59+
```
60+
61+
## Repository Layout
62+
63+
- `src/kc-accessibility/` mod source
64+
- `lib/` required game and native dependencies
65+
- `scripts/` stage and deploy helpers
66+
- `doc/` public documentation
67+
- `local/` ignored local-only research and notes
68+
69+
## Key Documentation
70+
71+
- [Controls Spec](doc/accessibility-control-scheme-spec.md)
72+
- [Architecture](doc/architecture.md)
73+
- [Manual Regression Checklist](doc/manual-accessibility-regression-checklist.md)
74+
75+
## Logging
76+
77+
The mod writes explicit runtime logs intended to support manual accessibility verification. When testing changes, check:
78+
79+
- the mod-specific `output.txt`
80+
- the game's general mods log
81+
82+
Keep logging stable and meaningful. Accessibility behavior in this project is verified primarily through build success plus in-game testing and log review.
83+
84+
## Development Notes
85+
86+
- `mod/` is generated output and should not be edited manually
87+
- deployed game files should be updated via the deploy script, not by hand
88+
- local-only investigation material belongs under `local/`, not in tracked source

‎doc/accessibility-control-scheme-spec.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Accessibility Control Scheme
2+
3+
This document describes the accessibility-oriented control model used by the mod and the intended direction for nearby follow-up work.
4+
5+
Some items are already implemented, while others remain part of the planned control model. The intent should stay stable even when implementation details change.
6+
7+
## Scope Rule
8+
9+
Unless a dedicated island-cycling command is used, navigation and discovery commands should stay within the current island.
10+
11+
## Movement
12+
13+
- `E S D F` move 1 tile
14+
- `Shift + E S D F` move 10 tiles
15+
16+
Movement speech should prefer:
17+
18+
- content type, if present
19+
- otherwise tile type
20+
- then coordinates
21+
22+
## Keep Navigation
23+
24+
- `H` announce relative position to the current island keep
25+
- double `H` move to the keep
26+
27+
Example:
28+
29+
`14 east, 6 south`
30+
31+
## Matching-Tile Cycling
32+
33+
- `W` next closest matching tile
34+
- `Shift + W` previous matching tile
35+
36+
Rules:
37+
38+
- match on content type first, otherwise tile type
39+
- sort by distance
40+
- use a stable clockwise tie-breaker
41+
- if no match exists, say `No other matching tiles`
42+
43+
## Bookmarks
44+
45+
- `Ctrl + digit` set bookmark
46+
- `digit` jump to bookmark
47+
- named bookmarks are planned but should remain explicit and spoken
48+
49+
Jump speech should include:
50+
51+
- bookmark name if present
52+
- tile or content description
53+
- coordinates
54+
55+
## Mesh Awareness
56+
57+
- `V` single press: surrounding-tile readout
58+
- second quick press: grouped summary
59+
60+
The readout should:
61+
62+
- use a stable order
63+
- avoid unnecessary direction words
64+
- stay short enough for practical play
65+
66+
## Directional Helpers
67+
68+
- `Ctrl + V` then direction: directional mesh
69+
- `Alt + direction`: directional scan
70+
- `Ctrl + direction`: directional summary
71+
72+
These helpers should provide structured, compact speech and avoid silent failures.
73+
74+
## Resource Access
75+
76+
- `R` open resource selection
77+
- `Ctrl + R` direct resource value prompt
78+
79+
Selecting a resource should speak the value and, where appropriate, may move focus to a relevant source tile on the current island.
80+
81+
## Actions
82+
83+
- `C` chop / cancel chopping
84+
- `B` open build menu
85+
86+
## Build Menu
87+
88+
Inside the build menu:
89+
90+
- category navigation should remain distinct from item navigation
91+
- selecting a building should lead into accessible placement handling
92+
- `Esc` should cancel or step back predictably
93+
94+
Placement mode should be sticky until explicitly canceled.
95+
96+
## Time Control
97+
98+
- `+` increase speed
99+
- `-` decrease speed
100+
101+
## Search and Discovery
102+
103+
Search-style helpers should:
104+
105+
- be island-scoped by default
106+
- use stable result ordering
107+
- cache result sets when browsing through matches
108+
- give explicit feedback when no result exists
109+
110+
## Consistency Rules
111+
112+
- use the same word for the same thing
113+
- keep output order stable
114+
- keep speech short and structured
115+
- avoid silent failures
116+
- every action should give feedback

‎doc/architecture.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
The mod is a C# class library loaded by the Kingdoms and Castles mod runtime. It creates a persistent Unity host object that owns:
6+
7+
- screen-reader initialization and speech output
8+
- load/save announcements
9+
- accessibility input handling
10+
- Harmony patches for menu, mode, and camera/startup transitions
11+
12+
The code is organized around runtime behavior rather than by UI screen alone.
13+
14+
## Main Runtime Pieces
15+
16+
### `ScreenReaderLoadMod`
17+
18+
Entry point used by the game's mod loader.
19+
20+
Responsibilities:
21+
22+
- initialize native speech support during `Preload`
23+
- create the persistent host on `SceneLoaded`
24+
- issue the first load announcement
25+
- provide a single logging entry point for the mod
26+
27+
### `KCTolk`
28+
29+
Thin speech bridge around Tolk and direct NVDA fallback.
30+
31+
Responsibilities:
32+
33+
- resolve native DLLs from the mod folder
34+
- initialize Tolk
35+
- fall back to direct NVDA output when Tolk incorrectly resolves to SAPI while NVDA is active
36+
- keep native interop isolated from gameplay/menu logic
37+
38+
### `ScreenReaderLoadBehaviour`
39+
40+
Persistent Unity `MonoBehaviour` used for load/save event announcements.
41+
42+
Responsibilities:
43+
44+
- subscribe to `Broadcast.OnLoadedEvent`
45+
- announce save-load completion
46+
- stay alive across scene changes
47+
48+
### `ScreenReaderAccessibilityBehaviour`
49+
50+
Persistent Unity `MonoBehaviour` that owns accessibility navigation behavior.
51+
52+
Responsibilities:
53+
54+
- install Harmony patches
55+
- load mod keybindings and route input through the accessibility layer
56+
- temporarily disable the game's native keyboard bindings for the mod session
57+
- manage main-menu accessibility state
58+
- manage gameplay accessibility state
59+
- manage modal accessibility commands such as directional mesh and resource-slot prompts
60+
- route accessibility input
61+
- announce focus changes, values, and gameplay state
62+
- apply preferred gameplay camera angle on gameplay startup
63+
- keep logging stable for manual verification
64+
65+
This class is split into multiple partial files by feature area:
66+
67+
- main menu handlers
68+
- gameplay map handlers
69+
- gameplay discovery helpers
70+
- gameplay pending-command handlers
71+
- gameplay build handlers
72+
- gameplay panel handlers
73+
- gameplay panel accessibility helpers
74+
- menu and settings helpers
75+
- shared helpers
76+
- state
77+
- routing
78+
79+
## Input Model
80+
81+
The mod uses its own keybinding layer through `ModKeyBindings`. In gameplay, the accessibility behavior checks those bindings first and routes input into:
82+
83+
- map navigation
84+
- panel navigation
85+
- build menu navigation
86+
- discovery/search helpers
87+
- modal prompts such as resource slot selection and directional mesh selection
88+
- bookmark/resource/anchor features
89+
90+
The accessibility layer intentionally reuses the game's real UI and gameplay systems rather than building a parallel fake interface. During an active mod session it also suppresses the game's native keyboard bindings so the accessibility bindings remain authoritative.
91+
92+
## Patching Model
93+
94+
Harmony patches are used for high-signal events such as:
95+
96+
- main menu state transitions
97+
- console item hover/focus updates
98+
- settings menu enable
99+
- difficulty refresh
100+
- save/load UI setup
101+
- banner picker open/close
102+
- gameplay mode transitions
103+
- game start camera initialization
104+
105+
These patches are intentionally narrow and are used to observe or lightly steer the game rather than replace large systems.
106+
107+
## Logging Model
108+
109+
Logging is part of the verification strategy, not just debugging noise.
110+
111+
The mod logs:
112+
113+
- startup and initialization milestones
114+
- patch installation
115+
- accessibility announcements
116+
- optional input-debug traces
117+
- important gameplay navigation events
118+
119+
Guidelines:
120+
121+
- keep log messages explicit and stable
122+
- avoid vague messages that are hard to correlate with player actions
123+
- preserve enough signal to reconstruct a test session from `output.txt`
124+
125+
## Documentation Boundaries
126+
127+
Public repository documentation should stay focused on:
128+
129+
- how the mod works
130+
- how to build and test it
131+
- active bindings and behavior
132+
- architecture relevant to contributors
133+
134+
Local reverse-engineering notes, decompiled references, and machine-specific investigation material belong under ignored `local/` content, not in tracked public source.

0 commit comments

Comments
 (0)
⚡