Release/3.12 to master

agents.md → .agent/agents.md

@@ -34,19 +34,10 @@ This repository contains a Unity engine application located in the root of this
 1. Follow Unity's component-based architecture for modular and reusable game elements.
 2. Prioritize performance optimization and memory management in every stage of development.
 3. Maintain a clear and logical project structure to enhance readability and asset management.
+4. Always use a test driven approach when implementing new features (except for UI related features).
 
 Refer to Unity documentation and C# programming guides for best practices in scripting, application/game architecture, and performance optimization.
 
-### Localization files
-UI text should always get localized. Localization files are located in `Assets/StreamingAssets/text/`.
-- `Localization.English.txt` is the master file.
-- The format is `KEY,Value`.
-- When adding new text:
-1. Add the `KEY,English Value` to `Localization.English.txt`.
-2. Add a translated version `KEY,Translated Value` to *all* other relevant files (`Localization.German.txt`, `Localization.French.txt`, `Localization.Spanish.txt`, `Localization.Italian.txt`, etc.). Failing to do so will result in missing text for users of those languages.
-3. In C# code, use `new StringKey("val", "KEY")` to reference the text.
-4. For commonly used keys, add a static reference in `Assets/Scripts/Content/CommonStringKeys.cs`.
-
 ## Development environment
 Coding is intended to happen in a Windows environment.
 
@@ -56,17 +47,4 @@ Coding is intended to happen in a Windows environment.
 
 ## Unity version
 - Unity version can be found here: unity\ProjectSettings\ProjectVersion.txt
-- Before implementing or suggesting any Unity-related changes, always verify compatibility with the current Unity version.
-
-## Target operating systems
-The application is designed to run on the following operating systems:
-- Windows
-- Mac
-- Linux
-- Android
-
-## Project structure
-For project structure see `README.md`. Check this structure first when searching for content in the repostory to speed up finding it.
-
-## Application wiki
-Wiki documentation for the application can be found here: https://github.com/NPBruce/valkyrie/wiki
+- Before implementing or suggesting any Unity-related changes, always verify compatibility with the current Unity version.

.agent/gemini.md

@@ -0,0 +1 @@
+Always follow all rules set in `.agent\agents.md`.

.agent/rules/code-style-guide.md

@@ -0,0 +1,5 @@
+---
+trigger: always_on
+---
+
+Follow .net styleguides defined in valkyrie\.editorconfig

.agent/rules/project-structure.md

@@ -0,0 +1,69 @@
+---
+trigger: always_on
+---
+
+# Project structure and logic
+- The application is purely based on unities UI system (Canvas, UI elements) for creating the app user interface.
+- The unity project is located in folder `unity`.
+- There is only one scene in the unity project located at `unity\Assets\Scenes\Game.unity`.
+
+## Assets
+Assets are located in folder `unity/Assets`.
+
+### Unity plugins
+Unity plugins are located in folder `unity/Assets/Plugins`. The following plugins are used:
+- **Firebase**: Google Firebase App and Crashlytics for analytics and crash reporting.
+- **Ionic.Zip.Unity**: Library for handling ZIP files.
+- **LZ4 Compression**: Library for LZ4 compression.
+- **NativeFilePicker**: Native file picker for Android and iOS.
+- **StandaloneFileBrowser**: Native file browser for desktop platforms (Windows, macOS, Linux).
+- **TextMeshPro**: Advanced text rendering for Unity.
+
+## Code
+C# code is located in folder `unity/Assets/Scripts`.
+
+## Unit tests.
+Unit tests are located in folder `unity\Assets\UnitTests`.
+
+### Constants
+String constants are located in file `unity/Assets/Scripts/ValkyrieConstants.cs`.
+
+### UI components
+UI components are located in folder `unity/Assets/Scripts/UI`.
+
+### UI screens
+UI screens are located in folder `unity/Assets/Scripts/UI/Screens`.
+
+### Website
+The public GitHub website data is located in folder `web` and `index.html`.
+
+## GitHub data
+
+### GitHub actions
+GitHub actions are located in folder `.github/workflows/`.
+
+#### GitHub action scripts
+GitHub actions scripts are located in folder `valkyrie\workflowScripts`.
+
+### GitHub issue templates
+GitHub issues are located in folder `.github/ISSUE_TEMPLATE/`.
+
+## Libraries
+Additional c# helper libraries are located in folder `libraries`. Helper libraries are:
+- **FFGAppImport**: Imports assets from official FFG apps.
+- **ValkyrieTools**: Common helpers and Android JNI utilities.
+- **SetVersion**: Updates version numbers in build files.
+- **ObbExtract**: Extract files from Android OBB archives.
+- **IADBExtract / Injection / MoMInjection**: Tools to extract/convert game data to Valkyrie format.
+- **PuzzleGenerator**: Generates puzzle data.
+
+## Resources
+Resources are located in folder `unity/Assets/Resources`. Resource data contains:
+- External scripts: External files used for different purposes under `unity/Assets/Resources/Scripts/`
+- Fonts: Font files under `unity/Assets/Resources/Fonts/`
+- Sprites: Icons and other common images under `unity/Assets/Resources/Sprites/`
+
+## Build scripts
+There are two build scripts that can by used as alternative for building the application in Unity editor. For more information on build see [Developer guide](https://github.com/NPBruce/valkyrie/wiki/Developer-Guide).
+- `workflowScripts/build.bat` is a batch file for Windows.
+- `workflowScripts/build.ps1` is a PowerShell script for Windows. This file is used in the GitHub actions build pipeline (`github\workflows\buildAndOptionalRelease.yml`).

.agent/rules/target-operating-systems.md

@@ -0,0 +1,11 @@
+---
+trigger: model_decision
+description: When dealing with operating system related features (e.g. file storage)
+---
+
+## Target operating systems
+The application is designed to run on the following operating systems:
+- Windows
+- Mac
+- Linux
+- Android

.agent/rules/testing.md

@@ -0,0 +1,28 @@
+---
+trigger: always_on
+---
+
+- Generate unit tests for each file and each method
+   - Exception: UI related classes in `valkyrie\unity\Assets\Scripts\UI`
+- Unit Tests should always be located in `valkyrie\unity\Assets\UnitTests`
+- When new tests have been created/existing tests have been updated ask if Unit tests should be ran. Do not run Unit Tests without confirmation from the user.
+
+### Testing
+The project uses NUnit for unit testing, integrated into the Unity Test Runner.
+**IMPORTANT**: Do NOT try to run these tests using `dotnet test` or creating separate test projects. These tests rely on the Unity Engine and must be run within the Unity environment.
+
+#### Running Tests via Command Line (Windows / CI Procedure)
+The CI pipeline (`.github/workflows/CodeAndSecurityValidation.yml`) uses a PowerShell helper script (`workflowScripts/workflowHelper.ps1`) to run tests. You can emulate this locally using the following command (adjusting paths to your Unity installation):
+
+```powershell
+# Example command similar to CI (Run-UnityTests)
+& 'C:\Program Files\Unity\Hub\Editor\2019.4.41f1\Editor\Unity.exe' -batchmode -nographics -projectPath ".\unity" -runTests -testPlatform EditMode -testResults "test-results.xml" -logFile "test-results.log"
+```
+
+*Note: Ensure the Unity Editor is closed to prevent file lock issues.*
+
+#### Test Structure
+- Tests are located in `Assets/UnitTests/Editor`.
+- Tests generally verify parsing logic, content loading, and game rules (e.g., `QuestData`, `PuzzleCode`).
+- **Library Tests**: Code in the `libraries/` folder is part of the project. Tests for these libraries should be created in `Assets/UnitTests/Editor` and run via Unity, not as standalone projects.
+- Use `CultureInfo.InvariantCulture` for all locale-dependent parsing (e.g., `float.TryParse`) to ensure tests pass on all system locales.

.agent/rules/text-localization.md

@@ -0,0 +1,15 @@
+---
+trigger: model_decision
+description: When it is necessary to add UI related texts
+---
+
+### Localization files
+UI text should always get localized. Localization files are located in `Assets/StreamingAssets/text/`.
+- `Localization.English.txt` is the master file.
+- The format is `KEY,Value`.
+- When adding new text:
+1. Add the `KEY,English Value` to `Localization.English.txt`.
+2. **CRITICAL**: Add a translated version `KEY,Translated Value` to *all* other relevant files (`Localization.German.txt`, `Localization.French.txt`, `Localization.Spanish.txt`, `Localization.Italian.txt`, etc.) where the value is translated to the language specified in the filename **IMMEDIATELY**. Do not defer this task. Failing to do so will result in missing text for users of those languages.
+3. In C# code, use `new StringKey("val", "KEY")` to reference the text.
+4. For commonly used keys, add a static reference in `Assets/Scripts/Content/CommonStringKeys.cs`.
+5. **VERIFICATION**: Before finishing the task, use find_by_name or list_dir to list all Localization.*.txt files. Confirm that the new key has been added and translated to the respective file language to EACH file. Do not assume; verify.

.agent/rules/ui-guide.md

@@ -0,0 +1,81 @@
+---
+trigger: model_decision
+description: When implementing/changing UI components
+---
+
+# UI Guide
+
+This document outlines the UI system used in the Valkyrie application. The UI is primarily code-driven using a custom `UIElement` usage wrapper around Unity's native UI system.
+
+## Core UI Classes
+
+The UI system is built upon a few key classes located in `Assets/Scripts/UI`.
+
+### UIElement
+`UIElement` is the fundamental building block for all UI components. It wraps Unity's `Image`, `Text`, and `Button` components and handles positioning and styling.
+
+- **Usage**: Used for buttons, labels, and background images.
+- **Positioning**: Uses a custom "UIScaler unit" system to ensure resolution independence.
+- **Key Methods**:
+    -   `new UIElement(parent_transform)`: Creates a new element.
+    -   `SetLocation(x, y, width, height)`: Sets position and size in UIScaler units.
+    -   `SetText(string_key)`: Sets localized text.
+    -   `SetButton(action)`: Assigns a click action.
+    -   `SetImage(texture)`: Sets the background image.
+    -   `SetBGColor(color)`: Sets background color.
+
+### UIElementEditable
+Inherits from `UIElement`. Provides a text input field.
+- **Usage**: User input forms.
+- **Key Methods**:
+    -   `SetText(text)`: Initial value.
+    -   `GetText()`: Retrieve current value.
+    -   `SetSingleLine()`: Restricts input to a single line.
+
+### UIElementScrollVertical
+Inherits from `UIElement`. Creates a vertically scrollable area.
+- **Usage**: Lists, long descriptions.
+- **Key Methods**:
+    -   `GetScrollTransform()`: Returns the transform where child elements should be attached.
+    -   `SetScrollSize(size)`: Sets the total height of the scrollable content.
+
+### UIWindowSelectionList
+A helper class to create a popup selection window.
+- **Usage**: Dropdown replacements, file pickers.
+- **Key Methods**:
+    -   `AddItem(text, action)`: Adds a selectable item.
+    -   `Draw()`: Renders the popup.
+
+## Screen Structure
+
+Screens are typically `MonoBehaviour` classes that manage the lifecycle of a specific view (e.g., `MainMenuScreen`, `QuestSelectionScreen`).
+
+- **Lifecycle**:
+    -   `Start()`: Initialization.
+    -   `Show()`: Builds the UI elements.
+    -   `Clean()`: Destroys UI elements (often by tag).
+- **Tagging**: Elements are often tagged (e.g., `Game.QUESTUI`) to facilitate bulk destruction when switching screens.
+
+## Quest Editor UI
+
+The Quest Editor uses a component-based approach for its UI, defined in `Assets/Scripts/QuestEditor`.
+
+### EditorComponent
+The base class for all editor components (Quest, Monster, Token, etc.).
+- **Responsibility**: Manages the UI for editing properties of a `QuestComponent`.
+- **Update Cycle**:
+    -   `Update()`: Re-renders the entire component UI.
+    -   `DrawComponentSelection()`: Standard buttons (Rename, Delete).
+    -   `AddSubComponents()`: Override this to add component-specific fields.
+
+### Example: Adding a Field to an Editor Component
+To add a new editable field to an `EditorComponent`:
+1.  Define a `UIElementEditable` field in the class.
+2.  In `AddSubComponents()`, instantiate the element and set its location.
+3.  Bind a button action (usually on the element itself or a separate button) to a method that updates the underlying data model.
+4.  Implement the update method (e.g., `UpdateQuestName()`) which reads the value from the UI element, updates the data, and calls `Update()` to refresh.
+
+## Styling & resources
+- **Fonts**: Accessed via `Game.Get().gameType.GetFont()`.
+- **Colors**: Standard Unity `Color` structs. `Color.clear` is often used for invisible click targets.
+- **UIScaler**: Provides helper methods for responsive sizing (`GetPixelsPerUnit()`, `GetSmallFont()`, `GetLargeFont()`).

.agent/rules/wiki.md

@@ -0,0 +1,7 @@
+---
+trigger: model_decision
+description: When unclear how business logic of a feature works
+---
+
+## Application wiki
+To better understand how the application works, please read the GitHub Wiki documentation at https://github.com/NPBruce/valkyrie/wiki