OpenBumpy - Documentation Blueprint & Standards Manual
1. Project Overview & Philosophy
- Author: Luc Calaresu (luc@calaresu.com)
- Project Name: OpenBumpy (Bumpy's Arcade Fantasy Modern Remake)
- Core Technology Stack: Custom 2D Game Engine built using C# and MonoGame (.NET).
- Architecture Philosophy: Strict end-to-end traceability. Every gameplay mechanic discovered via reverse engineering must be explicitly linked down to its functional requirement, software technical design, and automated/manual test execution blocks.
- Automation Friendliness: Documents are managed using StrictDoc (.sdoc). This allows automated tools to extract metrics, map test coverage, and generate the Requirements Traceability Matrix (RTM).
- Version: 1.0
2. The Documentation Suite Lifecycle (The Hierarchy)
The documentation suite is split into six distinct standalone documents that must be authored chronologically as development progresses.
2.1. Document Descriptions & Roles
- [DBSM] Documentation Blueprint & Standards Manual: Governance, coding style guides, documentation rules, and parsing parameters.
- [GDD] Game Design Document: Functional breakdown of the 1992 game mechanics and physics logic.
- [FRD] Functional Requirements Document: Engine capacity checklist defining what the game engine must support.
- [SDD] Software Design Document: Technical codebase blueprint (Classes, Game loops, ECS structures). Also referred to as TDD / Technical Design Document.
- [STP] Software Test Plan: High-level testing philosophy, environments, and automated test run strategies.
- [STD] Software Test Description: Step-by-step unit and integration test scripts to verify original behavior match.
2.2. Nomenclature & UID Prefixes Standard
To maintain strict global identification and structural alignment across the entire OpenBumpy technical stack, all elements within their respective documents MUST observe the following UID prefix conventions:
| Document | Type de contenu | Préfixe d'UID | Exemple d'UID |
|---|---|---|---|
| DBSM (Standards Manual) | Règles / Normes | RULE-OB- | RULE-OB-001 |
| GDD (Game Design) | Gameplay & Mechanics | GAME-OB- | GAME-OB-012 |
| FRD (Functional Req.) | Exigences Func. | REQ-OB- | REQ-OB-045 |
| SDD (Software Design) | Architecture & Tech. | SPEC-OB- | SPEC-OB-008 |
| STP (Test Plan) | Stratégie & Jalons | PLAN-OB- | PLAN-OB-002 |
| STD (Test Description) | Cas de tests op. | TEST-OB- | TEST-OB-103 |
2.3. Vertical Mapping Framework
Requirements MUST trace linearly downstream to ensure absolute verification coverage. This vertical relationship dictates that every engineering level directly answers or validates its upstream parent:
- A Functional Requirement (FRD) item explicitly targets and maps back to its parent Game Design (GDD) specification.
- A Software Design (SDD) component targets and maps back to the specific Functional Requirement (FRD) block it fulfills.
- A Software Test Description (STD) test script links directly to the Software Design (SDD) or Functional Requirement (FRD) component it exercises via StrictDoc RELATIONS.
3. Specification Writing Standards
This chapter defines the mandatory rules, syntax, and formatting conventions for writing project requirements. Every specification documented within this project MUST comply with these quality criteria to ensure clarity, testability, and unambiguous interpretation by all project stakeholders.
3.1. Requirement Verification Methods
Every specification MUST be assigned an explicit verification method to guarantee testability. Compliance MUST be proven using one of these four engineering standards:
- Test (T): Actively running the software or engine using automated tools and test scripts to collect exact numerical data. * Example: Executing a C# xUnit test to check bounding box collision responses.
- Demonstration (D): Operating the game or user interface to visually observe a functional behavior without deep instrumentation. * Example: Verifying that clicking the "Quit Game" button safely closes the application.
- Inspection (I): Examining a static artifact, source code file, or document without compiling or executing the software. * Example: Reviewing a document file to check for correct specification text formatting.
- Analysis (A): Using math equations, physics simulations, or analytical data to prove a rule is met when direct testing is impossible. * Example: Proving mathematically that the jump equation prevents objects from passing through solid blocks.
3.2. Requirement Priority Definitions
The table below establishes the evaluation matrix used to assign the Priority field for each specification item:
| Priority Level | Technical Criteria | Impact of Non-Compliance |
|---|---|---|
| Critical | Core system functionality, safety regulation, or key. | The project or product cannot be delivered/deployed. |
| High | Major feature or critical performance metric required. | Serious degradation of utility; high workaround cost |
| Medium | Secondary feature, optimization, or enhancement. | Minor impact on operations; acceptable workaround. |
| Low | Aesthetic preference, minor convenience, QoL feature. | Negligible impact; can be deferred. |
3.3. Quality Rules & Specifications
3.3.1. RFC 2119 Keyword Usage
The author MUST write all compliance keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) in uppercase letters.
Ensures compliance keywords stand out visually and match standard RFC 2119 parsing engines.
1.0
Critical
RFC 2119
Inspection (I)
✅ The system MUST encrypt all stored passwords.
The author MUST NOT use ambiguous terms such as generally, fast, ideally, or user-friendly within a specification description.
Ambiguity leads to subjective testing and variance in implementation.
1.0
High
INCOSE Guide for Writing Requirements
Inspection (I)
❌ The webpage SHOULD load fast.
✅ The webpage MUST load within 200 ms.
The implementation team SHOULD document a technical justification whenever a SHOULD or SHOULD NOT requirement is bypassed.
Ensures that bypassing recommended practices is a deliberate, recorded engineering decision.
1.0
Medium
RULE-OB-001
RFC 2119
Inspection (I)
3.3.2. Sentence Structure and Architecture
Each specification description MUST contain exactly one unique requirement.
Compound requirements create partial verification states where a test is both passed and failed.
1.0
Critical
ISO/IEC/IEEE 29148:2018
Inspection (I)
❌ The device MUST weigh under 1 kg and it MUST be painted black.
✅ The device weight MUST be under 1 kg.
The author MUST write specification descriptions using the active voice.
Active voice explicitly assigns responsibility to a specific component or actor, eliminating ambiguity.
1.0
High
INCOSE Guide for Writing Requirements
Inspection (I)
❌ An email MUST be sent by the server.
✅ The server MUST send an email.
The author MUST structure every specification sentence using the sequence: [Subject] + [Keyword] + [Active Verb] + [Measurable Target or Condition].
Establishes syntactic consistency, allowing automated natural language processing (NLP) validation tools to audit specs.
1.0
High
RULE-OB-001, RULE-OB-005
INCOSE Guide for Writing Requirements
Inspection (I)
✅ The application [Subject] MUST log [Keyword + Active Verb] all errors [Condition].
The length of a specification description sentence SHOULD NOT exceed 15 words.
Shorter sentences maximize readability and minimize misinterpretation by non-native readers or suppliers.
1.0
Medium
INCOSE Guide for Writing Requirements
Inspection (I)
3.3.3. Metrics and Quantifiable Data
Every performance or physical criterion MUST include a quantifiable, testable numerical value.
Prevents arguments between validation engineers and developers over whether an unquantified goal was hit.
1.0
Critical
RULE-OB-002
ISO/IEC/IEEE 29148:2018
Inspection (I)
❌ The database MUST handle many connections.
✅ The database MUST support 5000 concurrent connections.
The author MUST express all physical units of measurement using the International System of Units (SI).
Avoids costly conversions and translation errors when working with global multi-tier supply chains.
1.0
High
RULE-OB-008
ISO 80000 (SI Standard)
Inspection (I)
❌ The cable length MUST be 10 feet.
✅ The cable length MUST be 3.0 m.
The author SHOULD use standard mathematical symbols (e.g., ≤, ≥, ±) to define acceptable boundary limits and tolerances.
Standardizes numerical windows and removes prose variations like "up to" or "at least".
1.0
Medium
RULE-OB-008
ISO/IEC/IEEE 29148:2018
Inspection (I)
✅ The operational temperature MUST remain within 25 °C ± 5 °C.
3.3.4. Identification and Labeling Rules
The author MUST assign a unique identifier to every specification item across all project documentation that strictly matches the regular expression structure: ^[A-Z]{4,5}-OB-[0-9]{3,4}$.
Establishes a predictable text pattern allowing custom linting scripts and automated CI/CD tools to validate documentation parsing integrity.
2.0
Critical
Traceability Architecture Validation
Inspection (I)
✅ REQ-OB-045
✅ RULE-OB-011
The author MUST restrict the prefix of requirements to one of the exact six system tokens defined in the Nomenclature Standard: RULE-OB-, GAME-OB-, REQ-OB-, SPEC-OB-, PLAN-OB-, or TEST-OB-.
Ensures immediate structural identification of requirement ownership and context mapping across the technical stack.
2.0
Critical
RULE-OB-011
Traceability Architecture Validation
Inspection (I)
The author MUST format the numeric ID variable as a sequential integer left-padded with zeros up to a minimum length of three digits.
Fixed-width numeric padding protects table layout alignment and guarantees correct alphabetical sorting inside tools.
2.0
High
RULE-OB-011
Project Automation Standard
Inspection (I)
❌ REQ-OB-5
✅ REQ-OB-005
3.3.5. Version Control and Lifecycle Management
The author MUST NOT reuse or reassign the ID of a deleted or deprecated specification.
Prevents historical data corruption and tracking matrix mismatches across old releases.
1.0
Critical
RULE-OB-011
Regression Prevention Plan
Inspection (I)
✅ If RULE-OB-009 is retired, its ID remains archived eternally.
The author MUST update the STATUS field to Deprecated when a specification is retired from the project scope.
Flags old requirements cleanly, allowing databases to filter out inactive scope elements instantly.
1.0
High
Regression Prevention Plan
Inspection (I)
The author MUST increment the version number by a step of 0.1 for minor cosmetic changes and by 1.0 for major technical modifications.
Tracks iteration impact levels, indicating to down-line managers if a verification reset is needed.
1.0
Medium
Regression Prevention Plan
Inspection (I)
The author MUST provide non-empty values for RATIONALE, DEPENDENCIES, and VERIFICATION_METHOD within every specification item.
Guarantees absolute auditing capability, dependency resolution, and test mapping for all requirements.
1.0
Critical
RULE-OB-004
Verification Standard
Inspection (I)