Den Original™ Player Requirements System

[portfiend]

About the PR

This PR basically rewrites WizDen's JobRequirements to be cleaner and more flexible. "Requirement checking" logic has been decoupled from "reason string" logic, and it's much easier to add new requirement parameters and requirement types. The APIs for requirement checking are much more straightforward.

This is drawing a lot from my prebase refactor work on CharacterRequirements.

Why / Balance

We used that requirement system A LOT, and my refactors to the prebase system made it pretty easy to add new requirements. In addition, this system should make it possible to run requirements through tests, as making all parameters of the requirements optional means that we can skip over irrelevant requirements.

This is needed for traits and loadouts etc.

Technical details

IPlayerRequirement is a new interface for defining a "player requirement". IPlayerRequirements all have the following fields and methods:

• bool Inverted: Whether or not this requirement should be inverted. Fails become passes and vice versa.
• bool MustPassPreCheck: If a context fails the pre-check, normally it would count as an auto-pass so that the requirement gets "ignored" in checks. If this is enabled, instead, requirements that fail pre-checking will auto-fail.
• bool HideIfFailed: Whether or not the item associated with the requirement should be hidden from the player's UI if this requirement fails.
• bool PreCheck(PlayerRequirementContext context): This method checks a context to make sure all required fields are non-null.
• bool CheckRequirement(PlayerRequirementContext context): Performs the actual requirement check.
• string? GetReason(): Produces a "reason string" for a requirement. Notice how this logic is now decoupled from requirement checking!

There's also a new IPlayerRangeRequirement<T> interface, which can be used to add requirements that are characterized by nullifiable "minimum" and "maximum" range values.

CountRequirement is a data definition used for defining dynamic "count" fields for "overlapping list" requirements. For example, PlayerTraitRequirement has a HashSet<ProtoId<EntityTraitPrototype>> Traits datafield and a CountRequirement field, which allows you to define trait requirements as "at least 2 traits", "exactly 1", "all traits", et cetera.

PlayerRequirementContext is a new record definition that stores "contextual data" on the player that is being checked, like their current playtimes or selected character. All fields are nullable; null fields are "optional" and ignored in checks (at least, depending on MustPassPreCheck).

EntityTraits have requirements now! They're displayed in the UI. If you fail the requirements, they will not be applied to your character... however, keep in mind that admeme traits will ignore requirements!

JobPrototype and AntagPrototype now use IPlayerRequirements, and both JobRequirementsManager and PlayTimeTrackingSystem have been refactored to use these. Old requirement functionality has been preserved, but these are deprecated and all new requirements should use IPlayerRequirements.

The trait selector UI control has been updated to change visibility based on the HideIfFailed value of its requirements, as well as supply a requirement "reason" description as part of its tooltip.

Loadouts, antags, and job timer requirements have been migrated in YML to use the new player requirement system.

Playtesting Checklist

Sorry, this is a big ass PR. Here's the part that actually affects things in game

• All human morphotype traits should have a species requirement that restricts them to humans.
  • These traits should be hidden for other species in the character editor.
  • If you select the restricted morphotype trait, then switch species, then join the game, you should not have the morphotype trait.
• Adding a trait that fails requirements (such as the human morphotypes, as a non-human) using admin commands (e.g. self traits:add MorphHumanOni should still work.
• Jobs, traits, and antagonists should not have playtime requirements if the game.role_timers cvar is disabled.
• Loadouts should not have playtime requirements if the game.role_loadout_timers cvar is disabled.
• Every antagonist role visible in the lobby and nearly every job has playtime requirements. (Remember that most "intern" roles have maximum playtime requirements, as well!)
• These jobs have time-restricted loadouts: Cargo Technician, Quartermaster, Bartender, Chaplain, Janitor, Passenger, Captain, Head of Personnel, Chief Engineer, Station Engineer, Medical Doctor, Research Director, Scientist, Head of Security, Security Officer, Reporter, Clown.
• In addition, the following trinkets should be time-restricted: jamjar glasses, jensen glasses, clipboard, rainbow offset cane, striped offset cane, nanotrasen offset cane, the curved cane.

Media

Traits

Jobs

Antagonists

Loadouts

Requirements

• I have read and am following the Pull Request and Changelog Guidelines.
• I have added media to this PR or it does not require an in-game showcase.
• I have tested my changes and additions in-game.

Licensing

• All code in this pull request can be licensed to MIT.
• (OPTIONAL) I give permission to seeing this feature upstreamed to Macrocosm in the future.

Breaking changes

YML-side

The requirements field in job and antag prototypes has been deprecated. You should use the playerRequirements field instead for all future requirements. IPlayerRequirements have different syntax from JobRequirements, so you will need to find the corresponding player requirement to replace the old requirement.

Here is an example of old JobRequirement playtime fields:

requirements:
- !type:OverallPlaytimeRequirement
  time: 1h
- !type:RoleTimeRequirement
  role: JobStationEngineer
  time: 5h
- !type:DepartmentTimeRequirement
  department: Engineering
  time: 10h
  inverted: true

Here are their corresponding replacement IPlayerRequirements:

playerRequirements:
- !type:PlayerOverallPlaytimeRequirement
  minTime: 1h
- !type:PlayerJobPlaytimeRequirement
  job: StationEngineer
  minTime: 5h
- !type:PlayerDepartmentPlaytimeRequirement
  department: Engineering
  maxTime: 10h

In addition, loadouts have a new LoadoutEffect: PlayerRequirementLoadoutEffect. This should be used in place of JobRequirementLoadoutEffect in all future loadout requirements. For instance:

# OLD VERSION
- !type:JobRequirementLoadoutEffect
  requirement:
    !type:RoleTimeRequirement
    role: JobBartender
    time: 52h # 1 hour per week for 1 year

# NEW VERSION
- !type:PlayerRequirementLoadoutEffect
  requirement: !type:PlayerJobPlaytimeRequirement
    job: Bartender
    minTime: 52h
    requirementType: Loadout

The requirementType field, in this case, is either Role or Loadout, which determines which CVar gets used for toggling this playtime requirement on or off - the role timer cvar, or the loadout timer cvar.

Changelog
🆑

• tweak: Some playtime requirements on jobs and loadouts may read slightly different, to account for a new requirement system.
• tweak: Traits now use the new requirement system - this can be seen in morphotype traits, in particular.

[portfiend]

This PR is now ready for review. It's also a prerequisite for implementing loadouts and traits

[honeyed-lemons]

oh oops forgot to write a thing. The code is clean, well organized, and does its job. Comments seem to be in place everywhere they need to go, and play testing revealed everything works properly!

[sleepyyapril]

ill check it too later