From 388ee989dea20b1b550803848eebc83fd1cffa5e Mon Sep 17 00:00:00 2001 From: Nikita Hoffman Date: Sat, 14 Jan 2023 15:01:56 +0100 Subject: [PATCH] doc: documentation updated --- CONFIG.md | 120 +++++++++++++++++++++++++++++++----------------------- README.md | 102 +++++++++++++++++++++++++++++----------------- 2 files changed, 133 insertions(+), 89 deletions(-) diff --git a/CONFIG.md b/CONFIG.md index 4cf2d0a..6cfe209 100644 --- a/CONFIG.md +++ b/CONFIG.md @@ -1,4 +1,5 @@ # Command Manager Configuration + This Command Manager along with its dependent classes provide various configuration capabilities. The following guide will cover most (if not all) of them. @@ -7,6 +8,7 @@ All the configuration must reside in `N7CommandManager.ini` file. ## `N7_CommandManager` **Example:** + ```python [N7CommandManager.N7_CommandManager] # If False, all command requests will be ignored @@ -14,25 +16,27 @@ bAllowMutate=True ``` ## `N7_ColorManager` + In color manager one can set up their own set of colors by defining custom palettes. Each palette is a `struct` which represents a single color with finite number of tints. -Each palette has following tints: - * `T50` - * `T100` - * `T200` - * `T300` - * `T400` - * `T500` - * `T600` - * `T700` - * `T800` - * `T900` - * `A100` - * `A200` - * `A400` - * `A700` - -Tints are `struct Color` with `RGBA` format properties, so one tint can be defined as `(R=255,G=255,B=255,A=255)`. +Each palette has an `ID` which defines how a certain color/palette must be addressed, and the following tints: + +- `T50` +- `T100` +- `T200` +- `T300` +- `T400` +- `T500` +- `T600` +- `T700` +- `T800` +- `T900` +- `A100` +- `A200` +- `A400` +- `A700` + +Tints are `struct Color` with `RGBA` format properties, so one tint can be defined as `(R=255,G=255,B=255,A=255)`. It's not common that one will need to directly change the default palettes but just in case there is such an option. If you ever find yourself willing to override default palettes make sure you provide values for every tint inside a palette As unspecified tints will automatically resolve to default `(R=0,G=0,B=0,A=0)` which is a transparent color. @@ -40,66 +44,74 @@ As unspecified tints will automatically resolve to default `(R=0,G=0,B=0,A=0)` w Also one can change `DefaultColor` if needed. **Example:** + ```python [N7CommandManager.N7_ColorManager] DefaultColor=(R=255,G=255,B=255,A=255) # Tints that are omitted will resolve to transparent color (0,0,0,0) # So make sure to provide every tint with valid color value if you happen to override default colors -Reds=(T50=(R=255,G=255,B=255,A=255),T100=...) -Pinks=(T50=(R=255,G=255,B=255,A=255),T100=...) -Purples=(T50=(R=255,G=255,B=255,A=255),T100=...) -DeepPurples=(T50=(R=255,G=255,B=255,A=255),T100=...) -Indigos=(T50=(R=255,G=255,B=255,A=255),T100=...) -Blues=(T50=(R=255,G=255,B=255,A=255),T100=...) -LightBlues=(T50=(R=255,G=255,B=255,A=255),T100=...) -Cyans=(T50=(R=255,G=255,B=255,A=255),T100=...) -Teals=(T50=(R=255,G=255,B=255,A=255),T100=...) -Greens=(T50=(R=255,G=255,B=255,A=255),T100=...) -LightGreens=(T50=(R=255,G=255,B=255,A=255),T100=...) -Limes=(T50=(R=255,G=255,B=255,A=255),T100=...) -Yellows=(T50=(R=255,G=255,B=255,A=255),T100=...) -Ambers=(T50=(R=255,G=255,B=255,A=255),T100=...) -Oranges=(T50=(R=255,G=255,B=255,A=255),T100=...) -DeepOranges=(T50=(R=255,G=255,B=255,A=255),T100=...) -Browns=(T50=(R=255,G=255,B=255,A=255),T100=...) -Greys=(T50=(R=255,G=255,B=255,A=255),T100=...) -BlueGreys=(T50=(R=255,G=255,B=255,A=255),T100=...) +Reds=(ID="red",T50=(R=255,G=255,B=255,A=255),T100=...) +Pinks=(ID="pink",T50=(R=255,G=255,B=255,A=255),T100=...) +Purples=(ID="purple",T50=(R=255,G=255,B=255,A=255),T100=...) +DeepPurples=(ID="deeppurple",T50=(R=255,G=255,B=255,A=255),T100=...) +Indigos=(ID="indigo",T50=(R=255,G=255,B=255,A=255),T100=...) +Blues=(ID="blue",T50=(R=255,G=255,B=255,A=255),T100=...) +LightBlues=(ID="lightblue",T50=(R=255,G=255,B=255,A=255),T100=...) +Cyans=(ID="cyan",T50=(R=255,G=255,B=255,A=255),T100=...) +Teals=(ID="teal",T50=(R=255,G=255,B=255,A=255),T100=...) +Greens=(ID="green",T50=(R=255,G=255,B=255,A=255),T100=...) +LightGreens=(ID="lightgreen",T50=(R=255,G=255,B=255,A=255),T100=...) +Limes=(ID="lime",T50=(R=255,G=255,B=255,A=255),T100=...) +Yellows=(ID="yellow",T50=(R=255,G=255,B=255,A=255),T100=...) +Ambers=(ID="amber",T50=(R=255,G=255,B=255,A=255),T100=...) +Oranges=(ID="orange",T50=(R=255,G=255,B=255,A=255),T100=...) +DeepOranges=(ID="deeporange",T50=(R=255,G=255,B=255,A=255),T100=...) +Browns=(ID="brown",T50=(R=255,G=255,B=255,A=255),T100=...) +Greys=(ID="grey",T50=(R=255,G=255,B=255,A=255),T100=...) +BlueGreys=(ID="bluegrey",T50=(R=255,G=255,B=255,A=255),T100=...) ``` ## `N7_CommandMessageColors` + These are colors that will be used to colorize certain parts of messages/notifications. -Colors are defined using the following format: `:` | `rgb(0-255, 0-255, 0-255)` | `black` | `white`. +Colors are defined using the following format: `:` | `rgb(0-255, 0-255, 0-255)` | `black` | `white`. Message parts that support color highlighting: - * `Main` - Default color - * `Sender` - Command sender's name - * `Target` - Target name - * `Entity` - Non-living non-playable game entity. (e.g. Weapons) - * `Value` - Numeric/non-numeric value that is set when command gets executed - * `Signature` - Command signature when `help` is requested - * `Emphasis` - Important text that needs highlighting - * `Error` - Error messages + +- `Main` - Default color +- `Sender` - Command sender's name +- `Target` - Target name +- `Entity` - Non-living non-playable game entity. (e.g. Weapons) +- `Value` - Numeric/non-numeric value that is set when command gets executed +- `Signature` - Command signature when `help` is requested +- `Emphasis` - Important text that needs highlighting +- `Error` - Error messages **Example:** + ```python [N7CommandManager.N7_CommandMessageColors] Main="white" -Signature="white" -Sender="white" -Target="white" +Signature="blue:100" +Sender="rgb(100, 100, 100)" +Target="deeporange:a100" Entity="white" Value="white" Emphasis="white" -Error="white" +Error="red:a400" ``` +> **Note: When specifying a tint, `T` prefix should be omitted (e.g. `Blues.T100` -> `blue:100`), however this is not the case with tints prefixed by `A` (`Blues.A100` -> `blue:a100`)** + ## `N7_Command` + One usually won't want to configure this class directly. Instead it's better to change general command settings defined here for deriving command classes. The list of existing command classes can be found in this repository's `Classes/` directory. **Example:** + ```python [N7CommandManager.N7_] # If True only admins will be able to execute this command @@ -115,10 +127,12 @@ Aliases="THIRD" ``` ## `N7_TargetCommand` + All commands that are derived from `N7_TargetCommand` class share some targeting-related settings. These settings determine how strict the validation is towards selected targets. **Example:** + ```python [N7CommandManager.N7_] bOnlyAliveTargets=False @@ -130,21 +144,25 @@ bOnlyNonAdminTargets=False ``` ## `N7_GameSettingsCommand` + Most commands that use numeric value as an argument have lower and upper boundaries. Mostly these commands are derived from but not limited to `N7_GameSettingsCommand`. -To prevent configuring `MinLimit` with negative values +To prevent configuring `MinLimit` with negative values oftentimes out of `MinLimit` and `MaxLimit` params only the latter is configurable, but that's not always the case. Make sure you provide reasonable values when configuring these boundaries (avoid negative or inadequately large numbers) **Example:** + ```python [N7CommandManager.N7_] # In case command supports configuring MinLimit MinLimit=0 MaxLimit=10 ``` + ## Other commands + Other commands might have some specific configurable fields. -Feel free to explore them in the source code. Those are marked as `config`. +Feel free to explore them in the source code. Those are marked as `config`. diff --git a/README.md b/README.md index fb95248..d05cd99 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,41 @@ # N7 Command Manager ## Description + Killing Floor Mutate API initially designed and developed for Three Hundred Pounds server. Provides various commands for both players and admins to change game settings and trigger gameplay actions/events. ## Motivation + The motivation and reasoning behind development of the command manager is that most publicly available APIs have: - * Limited availability for certain actor groups (i.e. AdminPlus is admin-only API) - * Little potential for further extension (Adding new commands when needed, editing the existing ones) - * Poor configuration capabilities - * Inconsistent and not thorough validation mechanism + +- Limited availability for certain actor groups (i.e. AdminPlus is admin-only API) +- Little potential for further extension (Adding new commands when needed, editing the existing ones) +- Poor configuration capabilities +- Inconsistent and not thorough validation mechanism ## What N7CM is offering - * Large number of built-in commands - * Ability to provide multiple aliases for a single command (so it can be called in the way you are used to) - * Access configuration (Players/Spectators/Admins) - * MinMax values configuration for numeric arguments - * Rich and consistent validation for sender, targets, arguments, game state etc. - * Structure flexible enough to allow for API extension when new commands are needed - * Three-level notification system (for senders, for targets and global) - * Color highlighting configuration capabilities for certain parts of notifications/messages + +- Large number of built-in commands +- Ability to provide multiple aliases for a single command (so it can be called in the way you are used to) +- Access configuration (Players/Spectators/Admins) +- MinMax values configuration for numeric arguments +- Rich and consistent validation for sender, targets, arguments, game state etc. +- Structure flexible enough to allow for API extension when new commands are needed +- Three-level notification system (for senders, for targets and global) +- Color highlighting configuration capabilities for certain parts of notifications/messages ## How to use + ### Regular Players + Regular players can use any non-admin command from this pack. The common signature is: `mutate [command] [...args]`. The list of available commands for players can be requested via `mutate help`. To get information or (if available) some extended details regarding specific command one can use `mutate help [command]`. ### Admins + Admins can use all of the regular commands + bunch of commands with admin-only access The list of available commands for admins can be requested via `mutate ahelp` or `mutate adminhelp` (check `N7_AdminHelpCommand` aliases). To get information or (if available) some extended details regarding specific admin command one can use `mutate ahelp [command]`. @@ -36,61 +43,73 @@ To get information or (if available) some extended details regarding specific ad > [`CONFIG.md`](./CONFIG.md) contains basic guidelines for command settings configuration ### Developers/Modders + For those who want to extend the existing API there is some more information in terms of internal structure of the command manager. #### `N7_CommandManager` + This is the entry file, the mutator itself that dispatches incoming `mutate` requests. Each of the available commands must be specified as a part of `N7_CommandManager.Commands` array. Initialization takes place in one of the command initializing methods: - * `InitHelperCommands()` - * `InitGameSettingsCommands()` - * `InitGameplayCommands()` - * `InitPlayerCommands()` -The distinction between commands initialized in these methods is purely aesthetic, just visual grouping. -Furthermore, each command must be stated in `enum ECmd` to have its own index in `N7_CommandManager.Commands` array. +- `InitHelperCommands()` +- `InitGameSettingsCommands()` +- `InitGameplayCommands()` +- `InitPlayerCommands()` + +The distinction between commands initialized in these methods is purely aesthetic, just visual grouping. +Furthermore, each command must be stated in `enum ECmd` to have its own index in `N7_CommandManager.Commands` array. #### `N7_GameStateUtils` + This file contains some useful methods that can be applied in variety of commands and take significant number of code lines. Mostly these would affect some parts of ZEDs, players or game state. Each command has access to `N7_GameStateUtils` via `GSU` field which is defined in `N7_CommandManager` file. #### `N7_CommandValidator` -This class provides validation API that is used to check user input and various aspects of game state. + +This class provides validation API that is used to check user input and various aspects of game state. #### `N7_CommandExecutionState` + These classes keep track of command state when its execution is in progress. `N7_CommandExecutionState` contains information about current execution, namely: - * The Sender - * Targets (if there are any) - * Status and Error Code (if status is failed) - * Command Arguments + +- The Sender +- Targets (if there are any) +- Status and Error Code (if status is failed) +- Command Arguments It also allows for caching of some temporary values that are needed across different execution stages but need not be recalculated. It can cache: - * String - * TargetName - * Integer - * Float - * Boolean + +- String +- TargetName +- Integer +- Float +- Boolean #### `N7_Command` + Base class for all commands. Each new command must be derived from this class to inherit the base execution flow. The execution flow consists of 5 stages: - 1. `N7_CommandExecutionState` Initialization - Execution State literally gets its initial values. - 2. Arguments validation - Multi-step validation process when lots of conditions get checked (Gametype, Sender, Game State, Admin Access Restrictions etc.) - 3. Action Processing - Desired effects/actions are applied. - 4. Success/Error Notification - Depending on notification settings a selection of actors are notified about execution status. - 5. Optional Cleanup - If any values not related to `N7_CommandExecutionState` were used to keep track of execution progress those need to be reset. + +1. `N7_CommandExecutionState` Initialization - Execution State literally gets its initial values. +2. Arguments validation - Multi-step validation process when lots of conditions get checked (Gametype, Sender, Game State, Admin Access Restrictions etc.) +3. Action Processing - Desired effects/actions are applied. +4. Success/Error Notification - Depending on notification settings a selection of actors are notified about execution status. +5. Optional Cleanup - If any values not related to `N7_CommandExecutionState` were used to keep track of execution progress those need to be reset. This flow is `final` and cannot be altered in subclasses. Usually one might want to override the following methods to alter the command execution: - * `Check...(N7_CommandExecutionState)` - Checker methods. - * `DoAction(N7_CommandExecutionState)` - This is where the actual action logic resides. - * `Notify...(N7_CommandExecutionState)` - Notifications. -#### `N7_GameSettingsCommand`/`N7_TargetCommand` etc. +- `Check...(N7_CommandExecutionState)` - Checker methods. +- `DoAction(N7_CommandExecutionState)` - This is where the actual action logic resides. +- `Notify...(N7_CommandExecutionState)` - Notifications. + +#### Command Classes (`N7_GameSettingsCommand`, `N7_TargetCommand` etc) + Classes derived from `N7_Command` which provide common logic for specified sets of commands. `N7_GameSettingsCommand` provides some configuration and settings for commands whose sole purpose is to change @@ -99,11 +118,17 @@ some game settings be it maximum players number or ZED-time status. `N7_TargetCommand` provides extended logic for commands that affect a selection of players. Here resides the common logic for target validation and per-target command execution. +#### Models (`N7_HPConfigModel`, `N7_FakedPlayersModel` etc) + +Models' only purpose is exposing some of the game-/command-related APIs to `N7_CommandManager` +so it does not get overwhelmed with data management functionality. + #### `N7_ColorManager`/`N7_CommandMessageColors` + These classes are responsible for coloring of messages and notifications. `N7_ColorManager` is the class that provides color collection based on [Material Design colors](https://materialui.co/colors/). -It also provides API for text coloring and color picking based on IDs rather than RGBA structs. +It also provides API for text coloring and color picking based on IDs rather than RGBA structs. All color IDs follow the same structure: `:`. Also `black`, `white` or `rgb(byte, byte, byte)` compliant values are supported. Information on both colors and tints can be found on Material Design colors page. @@ -112,6 +137,7 @@ It is also responsible for providing colorization API for commands. One is not strictly tied to the cases defined in base `N7_CommandMessageColors` class as it can be extended and assigned to `N7_CommandManager.ColorsClass` field. ## Contacts + For questions/concerns/recommendations you can contact me via steam or email: **Steam Profile:** [N7n](https://steamcommunity.com/id/NSHoffman/)