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. + +
+ +---