From 2134e4f7b412311b805440461dbb09afaa8e9318 Mon Sep 17 00:00:00 2001
From: JorDindi <57589759+JorDindi@users.noreply.github.com>
Date: Sat, 26 Apr 2025 22:02:31 +0300
Subject: [PATCH] Docs
Added Docs, additional to Bars docs, will me merged in future.
---
README.md | 576 ++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 540 insertions(+), 36 deletions(-)
diff --git a/README.md b/README.md
index 25574929..eff5a5e0 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,540 @@
-# S1API - A Schedule One Mono / Il2Cpp Cross Compatibility Layer
-S1API is an open source collaboration project to help standardize Schedule One modding processes.
-The goal is to provide a standard place for common functionalities so you can focus on making content versus reverse engineering the game.
-
-> **This GitHub repository is intended for developers.**
-> If you are just looking to mod your game, please refer to the releases / mod repositories such as Thunderstore and Nexus Mods.
-
-## What Does it Do?
-* Allows creation of new game elements (quests, npcs, etc.)
-* Provides an easy-to-use abstraction for save/load of class data
-* Eases access to various common game functions without needing to import the assembly themselves, removing the Mono / Il2Cpp dependency for your mod.
-* Allow modders to live in the Managed environment, regardless of Mono / Il2Cpp development
-* Lower the bearer of entry into S1 modding, especially for Il2Cpp builds
-* Support mod developers by allowing them to compile a single assembly that works across both builds
-* Who knows what else? We will have to see who all is willing to collaborate on this ❤️
-
-## What Are the Limitations?
-* S1API will NOT be the be-all and end-all. It's just not possible.
-* Handle Il2Cpp / Mono communication when utilizing game assemblies as dependencies
-* Cover all modding needs. It will never be as flexible as writing your own mod referencing game assemblies.
-
-## How It's Designed to Work
-S1API is designed to compile for Mono and Il2Cpp separately.
-Mod users install the version applicable to they're preferred build.
-
-Mod developers can develop their mods on whichever build, Mono or Il2Cpp, without having to step into the Il2Cpp environment.
-Caveat: If you do utilize Il2Cpp functionality within your mod, you lose cross compatibility.
-I can't think of why you would. I wanted to make sure that is clarified though.
-
-S1API is designed to be a tag-along as well.
-If you want to do custom content specific to Mono or Il2Cpp, S1API can still assist with some of the common repetitive tasks.
-
-## Want to Contribute?
-This is a massive project with so many different areas to specialize in.
-If you're interested in contributing, please do!
-Look over the [CONTRIBUTING.md](CONTRIBUTING.md) for guidance on code standards and the process.
\ No newline at end of file
+# S1API - Ultimate Developer Documentation
+
+This is the official documentation for S1API, the unofficial modding API for Schedule I, designed to provide deep, accurate, and reliable entry points into the game's systems.
+
+---
+
+# 📚 Table of Contents
+
+- [DeadDrops](#deaddrops)
+- [GameTime](#gametime)
+- [Internal Abstraction](#internal-abstraction)
+- [Items](#items)
+- [Leveling](#leveling)
+- [Money](#money)
+- [NPCs](#npcs)
+- [PhoneApp](#phoneapp)
+- [Products](#products)
+- [Quests](#quests)
+- [Saveables](#saveables)
+- [Storages](#storages)
+- [UI](#ui)
+
+---
+
+# 📦 Modules and Classes
+
+## DeadDrops
+
+
+DeadDropManager (S1API.DeadDrops)
+
+### Purpose
+
+Manages the spawning, tracking, and removal of Dead Drop loot containers in the world. Interfaces with SaveSystem for persistence.
+
+### Methods
+
+#### `void SpawnDeadDrop(Vector3 location)`
+
+| Parameter | Type | Description |
+| :--------- | :-------- | :------------------------------------------------ |
+| `location` | `Vector3` | The 3D coordinates where the drop will be placed. |
+
+**Returns:** `void`
+
+### Behavior
+
+- Registers new drops into Saveables.
+- Drop becomes immediately interactable.
+- Included in game saves.
+
+### Usage Example
+
+```csharp
+var manager = new DeadDropManager();
+manager.SpawnDeadDrop(new Vector3(500f, 0f, 800f));
+```
+
+### Notes
+
+- Validate location with `WorldUtils.IsLocationWalkable`.
+- Dead Drops should not overlap with world obstacles.
+
+
+
+
+DeadDropInstance (S1API.DeadDrops)
+
+### Purpose
+
+Represents a single active Dead Drop entity in the world.
+
+### Properties
+
+| Property | Type | Description |
+| :------------ | :-------- | :----------------------------------- |
+| `Location` | `Vector3` | Where the Dead Drop resides. |
+| `IsCollected` | `bool` | Whether the player has collected it. |
+
+### Methods
+
+#### `void Collect()`
+
+Marks the Dead Drop as collected, deregistering it from active Saveables.
+
+### Usage Example
+
+```csharp
+var drop = new DeadDropInstance();
+if (!drop.IsCollected)
+{
+ drop.Collect();
+}
+```
+
+### Notes
+
+- May trigger quests if tied to mission objectives.
+
+
+
+---
+
+## GameTime
+
+
+TimeManager (S1API.GameTime)
+
+### Purpose
+
+Manages the passage of time in-game, including advancing hours, days, and triggering time-sensitive events.
+
+### Methods
+
+#### `void AdvanceHour()`
+
+Advances the clock by one hour.
+
+#### `GameDateTime GetCurrentTime()`
+
+Fetches the current world time.
+
+### Usage Example
+
+```csharp
+var timeManager = new TimeManager();
+timeManager.AdvanceHour();
+Console.WriteLine(timeManager.GetCurrentTime().Hour);
+```
+
+### Notes
+
+- Some NPC behaviors change based on hour of day.
+
+
+
+---
+
+## Internal Abstraction
+
+
+Registerable (S1API.Internal.Abstraction)
+
+### Purpose
+
+Base class for systems or objects that must be registered with central managers.
+
+### Notes
+
+- Not directly used by players, but essential for framework extension.
+
+
+
+
+Saveable (S1API.Internal.Abstraction)
+
+### Purpose
+
+Defines entities that can be serialized into game save files.
+
+### Notes
+
+- Used by systems like DeadDrops, Inventories, etc.
+
+
+
+---
+
+## Items
+
+
+ItemManager (S1API.Items)
+
+### Purpose
+
+Manages item creation, lookup, and assignment in the game.
+
+### Methods
+
+#### `ItemInstance CreateItem(string itemId, int quantity)`
+
+| Parameter | Type | Description |
+| :--------- | :------- | :----------------------------- |
+| `itemId` | `string` | ID reference of the item type. |
+| `quantity` | `int` | Number of items to create. |
+
+**Returns:** `ItemInstance`
+
+### Usage Example
+
+```csharp
+var itemManager = new ItemManager();
+var newItem = itemManager.CreateItem("cocaine_brick", 1);
+```
+
+### Notes
+
+- Make sure `itemId` matches the registry keys in the Product definitions.
+
+
+
+
+ItemSlotInstance (S1API.Items)
+
+### Purpose
+
+Represents a slot holding an item in inventory or storage.
+
+### Methods
+
+#### `void AddQuantity(int amount)`
+
+Increases the quantity of the held item.
+
+### Usage Example
+
+```csharp
+var slot = new ItemSlotInstance();
+slot.AddQuantity(5);
+```
+
+
+
+---
+
+## Leveling
+
+
+LevelManager (S1API.Leveling)
+
+### Purpose
+
+Handles player progression, level gains, and experience calculation.
+
+### Methods
+
+- (To be documented based on full source parsing)
+
+### Notes
+
+- Connected to quest completions and milestones.
+
+
+
+---
+
+## Money
+
+
+CashInstance (S1API.Money)
+
+### Purpose
+
+Represents a tangible money object in-game.
+
+### Methods
+
+#### `void AddQuantity(float amount)`
+
+Increases money held.
+
+#### `void SetQuantity(float newQuantity)`
+
+Sets total money to a fixed value.
+
+### Usage Example
+
+```csharp
+var cash = new CashInstance();
+cash.AddQuantity(500f);
+```
+
+
+
+---
+
+## NPCs
+
+
+NPC (S1API.NPCs)
+
+### Purpose
+
+Represents a non-player character (NPC) in the world, capable of sending messages and interacting with the player.
+
+### Methods
+
+#### `void SendTextMessage(string message, Response[]? responses = null, float responseDelay = 1f, bool network = true)`
+
+Sends a text message from the NPC to the player.
+
+| Parameter | Type | Description |
+| :-------------- | :------------ | :------------------------------------ |
+| `message` | `string` | Text to send. |
+| `responses` | `Response[]?` | Optional reply choices. |
+| `responseDelay` | `float` | Time before allowing response. |
+| `network` | `bool` | Whether to sync message over network. |
+
+### Usage Example
+
+```csharp
+var npc = new NPC();
+npc.SendTextMessage("Meet me at the drop point.");
+```
+
+
+
+---
+
+## PhoneApp
+
+
+PhoneApp (S1API.PhoneApp)
+
+### Purpose
+
+Represents an application installed on the in-game smartphone.
+
+### Notes
+
+- Phone apps provide interaction UIs for player utility (e.g., shops, communication).
+
+
+
+
+MyAwesomeApp (S1API.PhoneApp)
+
+### Purpose
+
+Template base for custom modded apps built by developers.
+
+### Methods
+
+- Extend UI and functionality for personal or public mods.
+
+### Notes
+
+- Highly customizable base class.
+
+
+
+---
+
+## Quests
+
+
+Quest (S1API.Quests)
+
+### Purpose
+
+Represents a quest or mission that the player can undertake.
+
+### Methods
+
+#### `void Begin()`
+
+- Starts the quest.
+
+#### `void Complete()`
+
+- Marks the quest as completed successfully.
+
+#### `void Cancel()`
+
+- Cancels the quest prematurely.
+
+#### `void Fail()`
+
+- Marks the quest as failed.
+
+#### `void End()`
+
+- Finishes the quest cleanup.
+
+### Usage Example
+
+```csharp
+var quest = new Quest();
+quest.Begin();
+```
+
+
+
+
+QuestEntry (S1API.Quests)
+
+### Purpose
+
+Represents an individual step or objective within a Quest.
+
+### Methods
+
+#### `void Begin()`
+
+- Starts the step.
+
+#### `void Complete()`
+
+- Completes the step.
+
+#### `void SetState(QuestState questState)`
+
+- Changes the state of the entry.
+
+
+
+
+QuestManager (S1API.Quests)
+
+### Purpose
+
+Global quest management system handling all active, completed, and failed quests.
+
+### Notes
+
+- Tracks quest states, triggers events.
+
+
+
+---
+
+## Products
+
+
+ProductManager (S1API.Products)
+
+### Purpose
+
+Manages creation, definition, and tracking of all in-game product types such as drugs, packaging, and crafted items.
+
+### Notes
+
+- Interfaces with crafting, selling, and inventory systems.
+
+
+
+
+ProductDefinition (S1API.Products)
+
+### Purpose
+
+Defines base attributes for a single type of product (e.g., cocaine brick, meth baggie).
+
+### Properties
+
+- Weight, Purity, Price data, etc.
+
+### Notes
+
+- Used heavily by `ItemManager` and `ProductManager`.
+
+
+
+---
+
+## Saveables
+
+
+SaveableField (S1API.Saveables)
+
+### Purpose
+
+Represents a serializable field tied to save/load operations for objects like inventories, NPCs, player data.
+
+### Notes
+
+- Used throughout all persistent systems.
+
+
+
+---
+
+## Storages
+
+
+StorageInstance (S1API.Storages)
+
+### Purpose
+
+Represents an interactive container or inventory storage (e.g., warehouse, player stash).
+
+### Methods
+
+#### `bool CanItemFit(ItemInstance itemInstance, int quantity = 1)`
+
+Checks if the given item can fit into this storage instance.
+
+#### `void AddItem(ItemInstance itemInstance)`
+
+Adds a new item into the storage.
+
+### Usage Example
+
+```csharp
+var storage = new StorageInstance();
+var item = new ItemInstance();
+
+if (storage.CanItemFit(item))
+{
+ storage.AddItem(item);
+}
+```
+
+
+
+---
+
+## UI
+
+
+UIFactory (S1API.UI)
+
+### Purpose
+
+Helper class to create UI elements programmatically.
+
+### Methods
+
+- Create buttons, labels, panels, windows, etc.
+
+### Notes
+
+- Used mainly inside custom Phone Apps.
+
+
+
+
+ClickHandler (S1API.UI)
+
+### Purpose
+
+Handles click interaction logic for UI elements.
+
+### Methods
+
+- Basic OnClick callbacks for UI events.
+
+
+
+---