diff --git a/projects/SimpleFactions/docs/vehicle-owners.md b/projects/SimpleFactions/docs/vehicle-owners.md index 09a7bac..fc0b753 100644 --- a/projects/SimpleFactions/docs/vehicle-owners.md +++ b/projects/SimpleFactions/docs/vehicle-owners.md @@ -90,8 +90,9 @@ VehicleFramework asks SimpleFactions about every player change through - Staff (`vf.admin`) are not refused, and their takeovers pay nothing; each staff claim, takeover and clear is logged as `[vehicle audit]`. - Any other change to a pool or installation vehicle is refused, including the - whitelist and ticket switches. The leader stamp only opens the ownership menu - and the seats. + whitelist, ticket, faction and guild switches. The leader stamp opens the + ownership menu and the seats, and lets the leader turn the allies and vassals + switches on or off. - A claim needs the claimer's current character, ready vehicle payments and a free personal slot, then pays the transfer fee when someone else owned the vehicle last. The first click shows the fee and the second pays it under the @@ -101,6 +102,19 @@ VehicleFramework asks SimpleFactions about every player change through drops the payer row but keeps the last owner, so a friend who claims the released vehicle still pays the transfer fee. +SimpleFactions also registers VehicleFramework's `VehicleAccessGroups` service +(VehicleFramework 2.15.0 or newer; with an older one it logs a warning and +vehicles keep their whitelists only). Group switches count from current +membership each time someone boards: + +- A pool or installation vehicle counts from its paying faction and always + admits that faction's members, whatever its leader stamp. +- Any other vehicle counts from its owner character's faction and guild. +- Guild means a player guild, as member or leader. A faction's main guild never + counts, and faction vehicles have no guild. +- Allies are the factions the vehicle's faction is allied with; vassals are its + direct vassals only. + SimpleFactions' own writes (construction, berthing, the pool, releases, handovers, installation transfers and leader stamps) go through VehicleFramework's `setOwnership`. The payer row is written first and put back if the owner write diff --git a/projects/VehicleFramework/docs/ownership.md b/projects/VehicleFramework/docs/ownership.md index 70c0544..d70e9a5 100644 --- a/projects/VehicleFramework/docs/ownership.md +++ b/projects/VehicleFramework/docs/ownership.md @@ -1,6 +1,6 @@ # Vehicle ownership -A vehicle has one owner value, a whitelist, a whitelist switch and ticket settings. VehicleFramework stores them in the vehicle's SQLite row (the `owner` column and the `payload_json` keys `owner`, `whitelist`, `whitelisted`, `ticketsEnabled` and `ticketId`). The [player guide](playing.md) covers the menus; this page covers identity, migration and the API other plugins use. +A vehicle has one owner value, a whitelist, a whitelist switch, group switches and ticket settings. VehicleFramework stores them in the vehicle's SQLite row (the `owner` column and the `payload_json` keys `owner`, `whitelist`, `whitelisted`, `accessGroups`, `ticketsEnabled` and `ticketId`). `accessGroups` lists the group switches that are on (`FACTION`, `GUILD`, `ALLY`, `VASSAL`) and is left out when none are. The [player guide](playing.md) covers the menus; this page covers identity, migration and the API other plugins use. ## Identity mode @@ -34,9 +34,24 @@ VehicleFramework never migrates owners itself. SimpleFactions converts legacy va "Type a Name" takes a character's real name in chat. Exactly one living character must have that name; no match and several matches give the same refusal. It needs TLibs 2.5.0 (`Characters.findByName`), which VehicleFramework checks once at startup; with an older TLibs the button is hidden and the picker still works. +## Group access + +Next to the whitelist, the owner can let whole groups board. Each group switch admits the members of one group, counted from the owner's current groups each time someone boards: + +| Switch | Admits | +| --- | --- | +| Faction | Members of the owner's faction | +| Guild | Members of the owner's player guild (a faction's main guild does not count) | +| Allies | Members of factions the owner's faction is allied with | +| Vassals | Members of the direct vassals of the owner's faction | + +A rider is admitted when they own the vehicle, are on its whitelist, or are in a group whose switch is on. The switches add to the whitelist and never change it, and like whitelist entries they only matter while the whitelist switch is on. If the owner leaves a faction or guild, that group stops counting at once. + +Group access needs `characters` mode and a ready `VehicleAccessGroups` service, which SimpleFactions provides. Without one the switches are hidden and admit nobody. The service can also open a group on a vehicle whatever its switch says: SimpleFactions does this for a pool or installation vehicle's own faction. + ## Claims, changes and takeovers -Characters mode clears the whitelist and turns it off when a vehicle is claimed, cleared or taken over, so a new owner never inherits the previous crew. `names` mode keeps the whitelist on claim and takeover and only turns it off when ownership is dropped. +Characters mode clears the whitelist, turns it off and turns every group switch off when a vehicle is claimed, cleared or taken over, so a new owner never inherits the previous crew. `names` mode keeps the whitelist on claim and takeover and only turns it off when ownership is dropped. Every change saves the vehicle at once. If the save fails, the vehicle keeps its previous values and the player is told nothing changed. @@ -64,15 +79,15 @@ The API is in `net.tfminecraft.vehicleframework.api` and the events in `net.tfmi | `readOwnershipMeta(UUID)` | The same for one vehicle. | | `setOwnership(UUID, OwnerChange, SystemReason)` | `OK`, `NOT_FOUND`, `SAVE_FAILED` or `REFUSED_MODE` (not in characters mode). | -`setOwnership` writes a loaded vehicle and saves it, putting the old values back if the save fails; it never falls back to the stored row. An unloaded vehicle has its owner column and payload rewritten in one SQLite transaction. Tickets never change. `OwnerChange` accepts `none`, `char_none` and `char_`; only `MIGRATE` may carry whitelist entries (`OwnerChange.seeded`). The reason decides the whitelist: +`setOwnership` writes a loaded vehicle and saves it, putting the old values back if the save fails; it never falls back to the stored row. An unloaded vehicle has its owner column and payload rewritten in one SQLite transaction. Tickets never change. `OwnerChange` accepts `none`, `char_none` and `char_`; only `MIGRATE` may carry whitelist entries (`OwnerChange.seeded`). The reason decides the whitelist and the group switches: -| Reason | Entries | Switch | -| --- | --- | --- | -| `RESTAMP` | kept | kept | -| `MIGRATE` | the seeded entries, or kept when none are given | kept | -| `CONSTRUCT` | emptied | on if `allow-whitelist` and `whitelisted-by-default` | -| `RELEASE`, `HANDOVER` | emptied | off | -| `TRANSFER` | emptied | kept | +| Reason | Entries | Switch | Group switches | +| --- | --- | --- | --- | +| `RESTAMP` | kept | kept | kept | +| `MIGRATE` | the seeded entries, or kept when none are given | kept | kept | +| `CONSTRUCT` | emptied | on if `allow-whitelist` and `whitelisted-by-default` | off | +| `RELEASE`, `HANDOVER` | emptied | off | off | +| `TRANSFER` | emptied | kept | off | `VehicleOwners` builds and parses owner values and whitelist entries. @@ -81,7 +96,7 @@ Events: | Event | When | | --- | --- | | `VehicleOwnershipEditCheckEvent` | Before an ownership-menu button is shown and again on every click. A pure check: `deny()` hides or refuses the control. An empty reason means opening the menu. | -| `VehicleOwnershipChangeEvent` | Before a player's change is written. Cancellable. Carries the vehicle actually changed (the locomotive for tickets), the reason (`CLAIM`, `CLEAR`, `TAKEOVER`, `WHITELIST_ADD`, `WHITELIST_REMOVE`, `WHITELIST_TOGGLE`, `TICKETS_TOGGLE`), an operation ID, the acting character, a staff flag, and the target character or raw whitelist entry. | +| `VehicleOwnershipChangeEvent` | Before a player's change is written. Cancellable. Carries the vehicle actually changed (the locomotive for tickets), the reason (`CLAIM`, `CLEAR`, `TAKEOVER`, `WHITELIST_ADD`, `WHITELIST_REMOVE`, `WHITELIST_TOGGLE`, `TICKETS_TOGGLE`, `FACTION_ACCESS_TOGGLE`, `GUILD_ACCESS_TOGGLE`, `ALLY_ACCESS_TOGGLE`, `VASSAL_ACCESS_TOGGLE`), an operation ID, the acting character, a staff flag, and the target character or raw whitelist entry. | | `VehicleOwnershipChangedEvent` | After the write, with the same operation ID, the outcome and the values before and after. For a player change it always fires once the change event has fired, including when the change was cancelled or the save failed. For `setOwnership` it fires only on `OK`. | `VehicleOwnerClaimedEvent` is removed. A listener that vetoes a claim must handle @@ -99,3 +114,4 @@ Services, looked up on every call: - `VehicleOwnershipAuthority`: SimpleFactions registers it once it handles the change events. `ready()` returning false counts as missing. - `VehicleQuarantineSource`: lists `QuarantinedVehicle` rows for `/vf admin quarantine`. Every registration is listed. +- `VehicleAccessGroups` (2.15.0): answers the group switches. `admits(group, vehicleId, owner, rider)` says whether the rider's character is in that group of the vehicle, `alwaysOpen` names groups the vehicle admits without its switch, and `describe` names the faction or guild for the menu. `ready()` returning false, a missing service or an exception admits nobody through groups. diff --git a/projects/VehicleFramework/docs/playing.md b/projects/VehicleFramework/docs/playing.md index 190706d..89465fc 100644 --- a/projects/VehicleFramework/docs/playing.md +++ b/projects/VehicleFramework/docs/playing.md @@ -73,12 +73,13 @@ From the seat menu, the owner can open ownership settings: - Remove someone from the whitelist. - Drop ownership. - Turn tickets on or off for this vehicle. On a train, tickets follow the locomotive, and only the locomotive's owner can change them. +- With characters and SimpleFactions, let whole groups board: the owner's faction, the owner's guild, factions allied with the owner's faction, and its direct vassals. Each group has its own switch in the second row, and the button names the faction or guild it counts from. A faction vehicle always admits its own faction; its leader can still open it to allies and vassals. See [Group access](ownership.md#group-access). Controls the player may not use are hidden, and every click is checked again. A chat prompt (whitelist name, vehicle name or takeover) ends after 60 seconds, and with characters also when the player stops playing the character that started it. -`allow-whitelist` and `whitelisted-by-default` in `config.yml` control whether new vehicles start with a whitelist. When the whitelist is on, other players need to be listed before the seat menu opens. +`allow-whitelist` and `whitelisted-by-default` in `config.yml` control whether new vehicles start with a whitelist. When the whitelist is on, other players need to be listed, or be in a group whose switch is on, before the seat menu opens. With `allow-whitelist: false` the group switches are hidden too. -Tickets use `ticket-item` (paper in the shipped config). The owner, or someone with `vf.admin`, right-clicks the vehicle with a blank ticket item while tickets are enabled. That writes a ticket for this vehicle. While tickets are on, a passenger seat requires that ticket unless the player is the owner or on the whitelist. A matching ticket also opens the seat menu when the whitelist would refuse the player. Captain, gunner, and mechanic seats do not ask for a ticket once the menu is open. +Tickets use `ticket-item` (paper in the shipped config). The owner, or someone with `vf.admin`, right-clicks the vehicle with a blank ticket item while tickets are enabled. That writes a ticket for this vehicle. While tickets are on, a passenger seat requires that ticket unless the player is the owner, on the whitelist or in an admitted group. A matching ticket also opens the seat menu when the whitelist would refuse the player, but then only passenger seats: captain, gunner and mechanic seats stay closed to them. When the whitelist is off, captain, gunner and mechanic seats do not ask for a ticket. ## Items in the main hand diff --git a/projects/VehicleFramework/docs/trains.md b/projects/VehicleFramework/docs/trains.md index 7e440ad..06a76b4 100644 --- a/projects/VehicleFramework/docs/trains.md +++ b/projects/VehicleFramework/docs/trains.md @@ -130,7 +130,7 @@ Do **not** require spawning the whole consist when one chunk loads. Accept tempo - loco YAML `fuel-cars` (vehicle ids). Each engine slow-tick, the loco drains one matching fuel item from containers on the car directly behind if that car's id is on the list. Empty list = no auto-drain. Cargo GUIs share one inventory so every viewer sees the take. - recorder item (`tracks.item-recorder`) stores throttle vs spline `s`, travel sign, and **hold ticks** at a stop (engine off still counts). Circuits only: recording runs until one full lap of the **origin** loop (or you cancel). Time on a siding is recorded but does not finish the lap. Samples may include `splineId`, `junction`, and body `orientation` (legacy default +1). Playback converts each sample from its recorded body orientation to the current train orientation; braking throttle can have the opposite sign to actual travel. Playback ramps throttle one step per tick (autopilot). Captain seat is manual (A/D still choose the frog); leaving resumes the tape from current `s`. Junction choice follows the physical switch and the consist’s occupied-route decisions; the tape does not throw switches. - Same-spline collision: if a locomotive dummy hitbox overlaps another train piece that is not on the same consist, those **two** vehicles explode when they close at `collision.explode-speed` blocks a second or more (default 3). The rest of each consist stays and uncouples. Slower, whichever train is moving into the other has its throttle and speed set to 0, as at a track end, and its captain is told. Each car's direction comes from how far it moved since the last tick, at its train's throttle speed, so a car placed or re-found on the track never counts as fast. A train touching another can still back away. Through vs branch at the frog does **not** explode (no frog AABB). [Collision warnings](using-trains.md#collision-warnings) give riders at least 30 seconds' notice while speeds stay as they are. [`TrainCollisionWarning`](https://github.com/TF-Minecraft/VehicleFramework/blob/main/src/main/java/net/tfminecraft/vehicleframework/tracks/TrainCollisionWarning.java) traces each moving train's route with `TrainRoute.trace`, one check further than `seconds`. [`CollisionForecast`](https://github.com/TF-Minecraft/VehicleFramework/blob/main/src/main/java/net/tfminecraft/vehicleframework/tracks/CollisionForecast.java) then steps each pair forward in 0.1-second steps, checking each train's head against the other's body as `TrainCollision` does. Each moving train's steps are worked out once per check, and the search stops at the soonest contact found so far. Unloaded cars come from the vehicle repository's in-memory index of saved track positions. Each car is re-found by its saved world position when its spline has gone or no longer runs under it, and counts as a head. Railroad switches use the configured `item-switch` ItemDisplay at each frog. -- generic vehicle tickets (planes too). Owner toggles in the ownership GUI. Passenger seats need a matching ticket; captain, gunner, mechanic, owner, and whitelist skip. Consist uses the loco ticket id. On coupled trains, whitelist and ticket settings use the locomotive (`ticketSource`); a loco ticket opens passenger seats on any connected car. Tickets are not consumed. +- generic vehicle tickets (planes too). Owner toggles in the ownership GUI. Passenger seats need a matching ticket; the owner, whitelist and admitted groups skip, and so do captain, gunner and mechanic seats while the whitelist is off. A ticket that gets a player past the whitelist only opens passenger seats. Consist uses the loco ticket id. On coupled trains, whitelist and ticket settings use the locomotive (`ticketSource`); a loco ticket opens passenger seats on any connected car. Tickets are not consumed. ## Validation