diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 57 |
1 files changed, 39 insertions, 18 deletions
@@ -1,11 +1,7 @@  -**SMAPI** is an [open-source](LICENSE) modding API for [Stardew Valley](http://stardewvalley.net/). -It takes care of loading mods into the game context, and exposes events they can use to interact -with the game. It's safely installed alongside the game's executable, and doesn't change any of -your game files. - ## Contents +* [What is SMAPI?](#what-is-smapi) * **[For players](#for-players)** * **[For mod developers](#for-mod-developers)** * [For SMAPI developers](#for-smapi-developers) @@ -16,6 +12,34 @@ your game files. * [Configuration file](#configuration-file) * [Command-line arguments](#command-line-arguments) +## What is SMAPI? +**SMAPI** is an [open-source](LICENSE) modding API for [Stardew Valley](http://stardewvalley.net/) +that lets you play the game with mods. It's safely installed alongside the game's executable, and +doesn't change any of your game files. It serves five main purposes: + +1. **Load mods into the game.** + _SMAPI loads mods when the game is starting up so they can interact with it. (Code mods aren't + possible without SMAPI to load them.)_ + +2. **Provide APIs and events for mods.** + _SMAPI provides low-level APIs and events which let mods interact with the game in ways they + otherwise couldn't._ + +3. **Rewrite mods for crossplatform compatibility.** + _SMAPI rewrites mods' compiled code before loading them so they work on Linux/Mac/Windows + without the mods needing to handle differences between the Linux/Mac and Windows versions of the + game._ + +4. **Rewrite mods to update them.** + _SMAPI detects when a mod accesses part of the game that changed in a recent update which + affects many mods, and rewrites the mod so it's compatible._ + +5. **Intercept errors.** + _SMAPI intercepts errors that happen in the game, displays the error details in the console + window, and in most cases automatically recovers the game. This prevents mods from accidentally + crashing the game, and makes it possible to troubleshoot errors in the game itself that would + otherwise show a generic 'program has stopped working' type of message._ + ## For players * [How to install SMAPI & use mods](http://canimod.com/guides/using-mods#installing-smapi) * [Release notes](release-notes.md#release-notes) @@ -26,7 +50,7 @@ your game files. * [How to develop mods](http://canimod.com/guides/creating-a-smapi-mod) * [How to update mods](http://canimod.com/guides/updating-a-smapi-mod) * [Release notes](release-notes.md#release-notes) -* [SMAPI/Farmhand Discord](https://discordapp.com/invite/0t3fh2xhHVc6Vdyx) (chat with SMAPI developers) +* [Chat on Discord](https://discord.gg/KCJHWhX) with SMAPI developers and other modders ## For SMAPI developers _This section is about compiling SMAPI itself from source. If you don't know what that means, this @@ -81,12 +105,10 @@ folder containing `src`). Mono/ Mods/* Mono.Cecil.dll - Mono.Cecil.Rocks.dll Newtonsoft.Json.dll StardewModdingAPI StardewModdingAPI.AssemblyRewriters.dll StardewModdingAPI.config.json - StardewModdingAPI.data.json StardewModdingAPI.exe StardewModdingAPI.exe.mdb steam_appid.txt @@ -95,11 +117,9 @@ folder containing `src`). Windows/ Mods/* Mono.Cecil.dll - Mono.Cecil.Rocks.dll Newtonsoft.Json.dll StardewModdingAPI.AssemblyRewriters.dll StardewModdingAPI.config.json - StardewModdingAPI.data.json StardewModdingAPI.exe StardewModdingAPI.pdb StardewModdingAPI.xml @@ -107,27 +127,28 @@ folder containing `src`). ``` 4. Open a terminal in the `SMAPI <version>` folder and run `chmod 755 internal/Mono/StardewModdingAPI`. 5. Copy & paste the `SMAPI <version>` folder as `SMAPI <version> for developers`. - 6. In the `SMAPI <version>` folder, delete the following files: - * `internal/Mono/StardewModdingAPI.config.json` - * `internal/Windows/StardewModdingAPI.config.json` - * `internal/Windows/StardewModdingAPI.xml` + 6. In the `SMAPI <version>` folder... + * edit `internal/Mono/StardewModdingAPI.config.json` and + `internal/Windows/StardewModdingAPI.config.json` to disable developer mode; + * delete `internal/Windows/StardewModdingAPI.xml`. 7. Compress the two folders into `SMAPI <version>.zip` and `SMAPI <version> for developers.zip`. ## Advanced usage ### Configuration file You can customise the SMAPI behaviour by editing the `StardewModdingAPI.config.json` file in your -game folder. If it's missing, it'll be generated automatically next time SMAPI runs. It contains -these fields: +game folder. It contains these fields: field | purpose ----- | ------- `DeveloperMode` | Default `false` (except in _SMAPI for developers_ releases). Whether to enable features intended for mod developers. Currently this only makes `TRACE`-level messages appear in the console. `CheckForUpdates` | Default `true`. Whether SMAPI should check for a newer version when you load the game. If a new version is available, a small message will appear in the console. This doesn't affect the load time even if your connection is offline or slow, because it happens in the background. +`ModCompatibility` | A list of mod versions SMAPI should consider compatible or broken regardless of whether it detects incompatible code. Each record can be set to `AssumeCompatible` or `AssumeBroken`. Changing this field is not recommended and may destabilise your game. ### Command-line arguments -SMAPI recognises the following command-line arguments. These are intended for internal use and may -change without warning. +SMAPI recognises the following command-line arguments. These are intended for internal use or +testing and may change without warning. argument | purpose -------- | ------- +`--log path "path"` | The relative or absolute path of the log file SMAPI should write. `--no-terminal` | SMAPI won't write anything to the console window. (Messages will still be written to the log file.) |