Add seatSetPath and make SitSpec fail-safe

[HazDS]

Add support for resolving seat sets by full hierarchy path (seatSetPath) and expose it on SitAtSeatSet. Change SitSpec to require a positive DurationMinutes (defaults to 60) and to disable the action (and deactivate its GameObject) with a logged warning when a seat set cannot be resolved to prevent NullReferenceExceptions. Update NPCScheduleBuilder API docs and the scheduling/seating registry documentation with examples, resolution order, and failure-handling guidance.

Release Notes

Changes

• Seat Set Resolution by Path: Added seatSetPath parameter to SitAtSeatSet method, enabling resolution of seat sets via full hierarchy path in addition to name-based lookup
• Fail-Safe Behavior: SitSpec now gracefully handles unresolved seat sets by disabling the action, deactivating its GameObject, and logging a warning instead of causing NullReferenceExceptions
• Duration Validation: DurationMinutes now defaults to 60 minutes and must be positive to trigger
• API Documentation: Updated NPCScheduleBuilder API docs and scheduling/seating registry documentation with detailed examples, resolution order (direct reference → path lookup → name lookup → NPC child search), and failure-handling guidance

Lines Changed by Contributor

Author	File	Added	Removed
HazDS	S1API/Entities/Schedule/ActionSpecs/SitSpec.cs	19	4
HazDS	S1API/Entities/Schedule/NPCScheduleBuilder.cs	19	8
HazDS	S1API/docs/scheduling-system.md	47	17
HazDS	S1API/docs/seating-registry.md	24	3
Total		109	32

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enhances the Sit scheduling action by introducing optional seatSetPath parameter for resolving seat sets via hierarchy paths alongside names. It updates NPCScheduleBuilder.SitAtSeatSet method signature, improves failure handling to disable actions when seat sets cannot be resolved, and expands documentation across scheduling and seating registry files.

Changes

Cohort / File(s)	Summary
Core Implementation S1API/Entities/Schedule/ActionSpecs/SitSpec.cs, S1API/Entities/Schedule/NPCScheduleBuilder.cs	Added optional seatSetPath parameter to SitAtSeatSet method; updated SitSpec to accept and store path for seat set resolution; enhanced failure handling to disable Sit action and log warnings when seat set cannot be resolved, preventing downstream errors.
Documentation S1API/docs/scheduling-system.md, S1API/docs/seating-registry.md	Expanded SitAtSeatSet and SitSpec documentation to describe new path-based lookup capability, resolution order (direct reference → path → name → NPC child search), positivity requirement for DurationMinutes, case-insensitive matching, and explicit failure handling behavior with code examples.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add Sit schedule action and duration support #52: Adds/modifies DurationMinutes and SitAtSeatSet parameter handling, directly overlapping with the duration and method signature changes in this PR.

Suggested reviewers

• ifBars

Poem

🐰 A seat set by name, or a path through the land,
The rabbit hops gleefully, understanding the plan,
When paths and names dance in resolution's embrace,
Failure is handled with warning and grace! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add seatSetPath and make SitSpec fail-safe' accurately summarizes the main changes: adding seatSetPath parameter support and implementing fail-safe behavior for SitSpec when seat sets cannot be resolved.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

S1API/docs/scheduling-system.md (1)

272-272: Minor style improvement for clarity.

The static analysis flagged a sentence fragment. Adding "It" as the subject improves readability.

📝 Suggested fix

-- `seatSetName`: GameObject name of the `AvatarSeatSet`. Can be `null` if `seatSetPath` is provided.
+- `seatSetName`: GameObject name of the `AvatarSeatSet`. It can be `null` if `seatSetPath` is provided.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@S1API/docs/scheduling-system.md` at line 272, Update the sentence describing
`seatSetName` to use a full sentence by adding a subject; change the fragment
"Can be `null` if `seatSetPath` is provided." to "It can be `null` if
`seatSetPath` is provided." in the `seatSetName` description that references the
`AvatarSeatSet` symbol.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@S1API/docs/scheduling-system.md`:
- Line 272: Update the sentence describing `seatSetName` to use a full sentence
by adding a subject; change the fragment "Can be `null` if `seatSetPath` is
provided." to "It can be `null` if `seatSetPath` is provided." in the
`seatSetName` description that references the `AvatarSeatSet` symbol.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c959a2f6-4fa0-435c-a407-6ec85bcce1b3

📥 Commits

Reviewing files that changed from the base of the PR and between 0a9c94d and 4c9727f.

📒 Files selected for processing (4)

• S1API/Entities/Schedule/ActionSpecs/SitSpec.cs
• S1API/Entities/Schedule/NPCScheduleBuilder.cs
• S1API/docs/scheduling-system.md
• S1API/docs/seating-registry.md