michael-dziedzic-VlZYu3nZIRI-unsplash.jpg

Project Design Document

Introduction

This project aims to simulate a weapon API (Application Programming Interface) for Honkai Impact 3rd using the Crow framework, a high-performance C++ microweb service framework, to facilitate interaction design.

It allows users to search from four various dimensions, access detailed information, and modify through a series of RESTful endpoints.

Background/Context

In the realm of ARPGs, character equipment and optimization play a crucial role in gameplay experience and strategy. Honkai Impact 3rd players often seek to enhance their performance by matching the best weapons with the appropriate Valkyries. The proposed weapon library will leverage the Crow framework to provide a structured and efficient means for players to access weapon information and recommendations, improving their strategic planning and gameplay satisfaction.

Stakeholders

  • Players: Primary users who will interact with the library to make informed decisions about weapon choices based on detailed attributes and recommendations.
  • Game developers: May use the library to display weapon data consistently and update weapon information through backend systems.

Functional Requirements

  1. Weapon Search

    • The system shall provide a search function that allows users to enter weapon names or filter by specific attributes (e.g., type, star level, element type).
    • The system shall display auto-complete suggestions as the user types to facilitate the search process.
    • The system shall return a 200 OK status code and the search results in the response body upon successful search execution.

  2. Weapon Information Display

    • The service shall provide endpoints that display detailed information about each weapon, including WeaponID, Name, Type, Star Level, Element Type, Attack Damage, Critical Hit, Recommended Valkyrie, and Description.
    • The service shall allow users to retrieve detailed information for a single weapon by its unique WeaponID.
    • The service shall return a 200 OK status code and the weapon information in the response body upon successful retrieval.

  3. Valkyrie Compatibility

    • The system shall display recommended Valkyries for each weapon to guide players in choosing the best Valkyries for their gameplay.
    • The system shall provide filtering options that allow users to display only the weapons compatible with a selected Valkyrie type.
    • The system shall return a 200 OK status code and the filtered weapon list in the response body upon successful filtering.

  4. Weapon Creation

    • The service shall allow authorized users to create new weapon entries via POST requests.
    • The service shall validate all incoming data against predefined schemas before creating a new weapon entry.
    • The service shall return a 201 Created status code and the created weapon information in the response body upon successful creation.

  5. Weapon Update

    • The service shall permit authorized users to update existing weapon entries via PUT requests.
    • The service shall validate all incoming data for updates against predefined schemas.
    • The service shall return a 200 OK status code and the updated weapon information in the response body upon successful update.

  6. Weapon Deletion

    • The service shall enable authorized users to delete weapon entries via DELETE requests.
    • The service shall return a 204 No Content status code upon successful deletion.
    • The service shall return a 403 Forbidden status code if an unauthorized user attempts to delete a weapon entry.

  7. Data Validation

    • The service shall enforce data validation rules to ensure that all weapon data conforms to expected formats, types, and constraints.
    • The service shall return a 400 Bad Request status code along with error details if validation fails.

  8. Authentication and Authorization

    • The service shall require authentication for users attempting to create, update, or delete weapon entries.
    • The service shall authorize users based on their roles, allowing only authorized personnel (game developers or community managers) to modify or delete weapon entries.

  9. Error Handling

    • The service shall implement comprehensive error handling to provide meaningful error messages and appropriate HTTP status codes to the client for all failed operations.
    • The service shall return a 404 Not Found status code when a requested weapon cannot be located.

Use Case Description

Weapons

  • Search (GET)

    • As a player, I want to search for weapons by name or filter them by attributes such as type, star level, or element, so that I can quickly find the best weapon options for my gameplay needs.

  • Create (POST)

    • As a game developer, I want to add new weapons to the database as they are introduced in game updates, so that the weapon library remains current and useful for players.

  • Read (GET)

    • As a player, I want to view detailed information about each weapon, including its stats, lore, and recommended Valkyries, to better understand how it can be utilized effectively in gameplay.

  • Update (PUT)

    • As a game developer, I want to update weapon entries to reflect balance changes or corrections to ensure the library provides accurate and up-to-date information.

  • Delete (DELETE)

    • As a game developer, I need to remove weapons that are no longer available in the game to keep the database clean and relevant.

Valkyries

  • Create (POST)

    • As a game developer, I want to add new Valkyrie profiles to the library as new characters are released in the game, ensuring players have access to the latest character information.

  • Read (GET)

    • As a player, I want to explore which Valkyries are recommended for specific weapons, to optimize my team setup and strategy.

  • Update (PUT)

    • As a game developer, I want to update Valkyrie profiles with new skills or affiliations as the game evolves.

  • Delete (DELETE)

    • As a game developer, I need to remove Valkyrie profiles for characters that are retired from the game to maintain an accurate and updated library.

Weapon Types

  • Create (POST)

    • As a game developer, I want to define new weapon types as the game introduces new categories, ensuring that the weapon classification in the library stays relevant.

  • Read (GET)

    • As a player, I want to filter weapons based on their type (e.g., Great Swords, Katanas) to find weapons that fit the combat style I prefer.

  • Update (PUT)

    • As a game developer, I need to update the definitions or characteristics of weapon types to align with game updates or changes in weapon mechanics.

  • Delete (DELETE)

    • As a game developer, I need to remove outdated weapon types if they are phased out of the game due to changes in gameplay mechanics.

Attributes

  • Create (POST)

    • As a game developer, I want to add new attributes that weapons can have as the game’s mechanics evolve, ensuring that all relevant attributes are trackable.

  • Read (GET)

    • As a player, I want to understand the attributes that affect weapon performance, such as Attack Damage or Critical Hit, to make better-informed decisions about weapon selection.

  • Update (PUT)

    • As a game developer, I need to update attribute descriptions or values as the underlying game mechanics change.

  • Delete (DELETE)

    • As a game developer, I need to remove attributes that are no longer used in the game to avoid confusion and maintain clarity in the weapon library.

List Of Resources

  • Weapons: Represents individual weapons in the game, including their specific attributes and related information. Each weapon entry includes the following attributes:

    • WeaponID: Unique identifier, e.g. W01
    • Name: e.g. Sleeper's Dream
    • Type: e.g. Great Swords
    • StarLevel: e.g. 5 (1-5 stars)
    • ElementType: e.g. Physical (Physical, Fire, Ice, Lightning)
    • AttackDamage: Integer value, e.g. 279
    • CriticalHit: Integer value, e.g. 37
    • RecommendedValkyrie: e.g. Rozaliya
    • Description: Narrative description, e.g. "A specialized greatsword crafted alongside Odette the Silent. Delta's best companion in battle. The dream has long faded, but the two greatswords are still keeping her company just like the old days."

  • Weapon Types: Categorizes weapons into their respective types, which facilitates easier browsing and searching based on weapon category. Each weapon type includes:

    • TypeID: Unique identifier, e.g. T01
    • TypeName: e.g. Great Swords
    • AttackRange: e.g. Melee (Melee, Medium, Long)

  • Valkyries: Contains information about the Valkyries in the game, focusing on their compatibility with different weapon types for optimized gameplay. Each Valkyrie profile includes:

    • ValkyrieID: Unique identifier, e.g. V01
    • Name: e.g. Rozaliya
    • PreferredWeaponType: e.g. Great Swords
    • Description: Narrative description, e.g. "Rozaliya Olenyeva is the twin sister of Liliya Olenyeva and an orphan at Cocolia's Orphanage."

  • Attributes: Explains the system of attributes by which weapons are evaluated. Unlike the first "Weapons" resource, this resource does not detail individual weapons but rather the attributes themselves. Each attribute includes:

    • AttributeID: Unique identifier, e.g. A01
    • AttributeName: e.g. Star Level
    • Description: Explanation of the attribute, e.g. "The more stars showing that the weapon is generally stronger than weapons which has a lower stars."

List of End Points

Weapons

  • POST /api/weapons

    • Description: Create a new weapon.
    • Request BODY: {"name": "Sleeper's Dream", "type": "Great Swords", "starLevel": 5, "elementType": "Physical", "ATK": 279, "CRIT": 37, "recommendedValkyrie": "Rozaliya", "description": "A specialized greatsword crafted alongside Odette the Silent."}
    • Response: 201 Created with the created weapon object in the body.
    • Error: 400 Bad Request if input validation fails.

  • GET /api/weapons

    • Description: Retrieve a list of all weapons.
    • Response: 200 OK with an array of weapon objects in the body.

  • GET /api/weapons/{id}

    • Description: Retrieve details of a specific weapon by its unique identifier.
    • Response: 200 OK with the weapon object in the body.
    • Error: 404 Not Found if the weapon does not exist.

  • PUT /api/weapons/{id}

    • Description: Update an existing weapon.
    • Request BODY: {"name": "Sleeper's Dream", "type": "Great Swords", "starLevel": 5, "elementType": "Physical", "ATK": 279, "CRIT": 37, "recommendedValkyrie": "Rozaliya", "description": "Updated description."}
    • Response: 200 OK with the updated weapon object in the body.
    • Error: 400 Bad Request if input validation fails; 404 Not Found if the weapon does not exist.

  • DELETE /api/weapons/{id}

    • Description: Delete a specific weapon.
    • Response: 204 No Content.
    • Error: 404 Not Found if the weapon does not exist; 403 Forbidden if the user is unauthorized.

Weapon Types

  • POST /api/weapontypes

    • Description: Add a new weapon type to the catalog.
    • Request BODY: {"typeName": "Great Swords", "attackRange": "Melee"}
    • Response: 201 Created with the created weapon type object in the body.
    • Error: 400 Bad Request if input validation fails.

  • GET /api/weapontypes

    • Description: Retrieve a list of all weapon types.
    • Response: 200 OK with an array of weapon type objects in the body.

  • GET /api/weapontypes/{id}

    • Description: Retrieve details of a specific weapon type by its unique identifier.
    • Response: 200 OK with the weapon type object in the body.
    • Error: 404 Not Found if the weapon type does not exist.

  • PUT /api/weapontypes/{id}

    • Description: Update an existing weapon type.
    • Request BODY: {"typeName": "Great Swords", "attackRange": "Long"}
    • Response: 200 OK with the updated weapon type object in the body.
    • Error: 400 Bad Request if input validation fails; 404 Not Found if the weapon type does not exist.

  • DELETE /api/weapontypes/{id}

    • Description: Remove a weapon type from the catalog.
    • Response: 204 No Content.
    • Error: 404 Not Found if the weapon type does not exist; 403 Forbidden if the user is unauthorized.

Valkyries

  • POST /api/valkyries

    • Description: Add a new Valkyrie profile to the catalog.
    • Request BODY: {"name": "Rozaliya", "preferredWeaponType": "Great Swords", "description": "Rozaliya Olenyeva is the twin sister of Liliya Olenyeva and an orphan at Cocolia's Orphanage."}
    • Response: 201 Created with the created Valkyrie object in the body.
    • Error: 400 Bad Request if input validation fails.

  • GET /api/valkyries

    • Description: Retrieve a list of all Valkyrie profiles.
    • Response: 200 OK with an array of Valkyrie objects in the body.

  • GET /api/valkyries/{id}

    • Description: Retrieve details of a specific Valkyrie by its unique identifier.
    • Response: 200 OK with the Valkyrie object in the body.
    • Error: 404 Not Found if the Valkyrie does not exist.

  • PUT /api/valkyries/{id}

    • Description: Update the profile of an existing Valkyrie.
    • Request BODY: {"name": "Rozaliya", "preferredWeaponType": "Great Swords", "description": "Updated description."}
    • Response: 200 OK with the updated Valkyrie object in the body.
    • Error: 400 Bad Request if input validation fails; 404 Not Found if the Valkyrie does not exist.

  • DELETE /api/valkyries/{id}

    • Description: Remove a Valkyrie profile from the catalog.
    • Response: 204 No Content.
    • Error: 404 Not Found if the Valkyrie does not exist; 403 Forbidden if the user is unauthorized.

Attributes

  • POST /api/attributes

    • Description: Add a new attribute to the catalog.
    • Request BODY: {"attributeName": "Star Level", "description": "The more stars showing that the weapon is generally stronger than weapons which has a lower stars."}
    • Response: 201 Created with the created attribute object in the body.
    • Error: 400 Bad Request if input validation fails.

  • GET /api/attributes

    • Description: Retrieve a list of all attributes.
    • Response: 200 OK with an array of attribute objects in the body.

  • GET /api/attributes/{id}

    • Description: Retrieve details of a specific attribute by its unique identifier.
    • Response: 200 OK with the attribute object in the body.
    • Error: 404 Not Found if the attribute does not exist.

  • PUT /api/attributes/{id}

    • Description: Update an existing attribute.
    • Request BODY: {"attributeName": "Star Level", "description": "Updated description."}
    • Response: 200 OK with the updated attribute object in the body.
    • Error: 400 Bad Request if input validation fails; 404 Not Found if the attribute does not exist.

  • DELETE /api/attributes/{id}

    • Description: Remove an attribute from the catalog.
    • Response: 204 No Content.
    • Error: 404 Not Found if the attribute does not exist; 403 Forbidden if the user is unauthorized.

UML Diagram

&

Code Sample

1.png
2.png
3.png
4.png