translators
8,404
edits
Changes
Jump to navigation
Jump to search
Line 52:
Line 52: − − ==Events== − SMAPI publishes several C# events that tell you when something happens. For example, if you want to do something after the player loads their save, you can add this to your <tt>Entry</tt> method: − − <source lang="c#"> − SaveEvents.AfterLoad += this.SaveEvents_AfterLoad; − </source> − − Then declare a method like this. (The <tt>EventArgs e</tt> argument contains any extra data about the event.) − − <source lang="c#"> − /// <summary>The method called after the player loads their save.</summary> − /// <param name="sender">The event sender.</param> − /// <param name="e">The event arguments.</param> − public void SaveEvents_AfterLoad(object sender, EventArgs e) − { − this.Monitor.Log("The player loaded their game! This is a good time to do things."); − this.Monitor.Log("Everything in the world is ready to interact with at this point."); − } − </source> − − The available events are documented below. − − ===Content events=== − <tt>ContentEvents</tt> are raised when the game loads content from its XNB files or changes locale. − {| class="wikitable" − |- − ! event !! summary − |- − | AfterLocaleChanged || Raised after the content language changes. − |} − − ===Control events=== − <tt>ControlEvents</tt> are raised when the player uses a controller, keyboard, or mouse. They're raised before the game handles the input, so it's possible to selectively prevent the game from responding to it. (That's beyond the scope of this guide, but it involves overwriting <tt>Game1.oldKBState</tt>, <tt>Game1.oldMouseState</tt>, and <tt>Game1.oldPadState</tt>.) − − Most of these events are split into two variants, <tt>XPressed</tt> and <tt>XReleased</tt>. The <tt>Pressed</tt> variant is raised when the player presses the button (holding the button down only triggers the event once), and the <tt>Released</tt> variant is raised when they release it. − − {{SMAPI upcoming|2.6|content='''Note:''' mods won't receive input sent to the chatbox, or the toggle-chatbox key.}} − − {| class="wikitable" − |- − ! event !! summary − |- − | ControllerButtonPressed<br />ControllerButtonReleased || Raised after the player pressed/released a button on a gamepad or controller. These events aren't raised for trigger buttons. − |- − | ControllerTriggerPressed<br />ControllerTriggerReleased || Raised after the player pressed/released a trigger button on a gamepad or controller. − |- − | KeyPressed<br />KeyReleased || Raised after the player pressed/released a keyboard key. − |- − | KeyboardChanged || Raised after the game's <tt>KeyboardState</tt> changed. That happens when the player presses or releases a key. − |- − | MouseChanged || Raised after the game's <tt>MouseState</tt> changed. That happens when the player moves the mouse, scrolls the mouse wheel, or presses/releases a button. − |} − − ===Game events=== − <tt>GameEvents</tt> are raised when the game changes state. − − {| class="wikitable" − |- − ! event !! summary − |- − | FirstUpdateTick || Raised after the game first updates its state. This happens once per game session (unrelated to loading saves). − |- − | UpdateTick || Raised when the game updates its state (≈60 times per second). − |- − | SecondUpdateTick || Raised every other tick (≈30 times per second). − |- − | FourthUpdateTick || Raised every fourth tick (≈15 times per second). − |- − | EighthUpdateTick || Raised every eighth tick (≈8 times per second). − |- − | QuarterSecondTick || Raised every 15th tick (≈4 times per second). − |- − | HalfSecondTick || Raised every 30th tick (≈twice per second). − |- − | OneSecondTick || Raised every 60th tick (≈once per second). − |} − − ===Graphics events=== − <tt>GraphicsEvents</tt> are raised during the game's draw loop, when the game is rendering content to the window. − − {| class="wikitable" − |- − ! event !! summary − |- − | OnPreRenderEvent<br />OnPostRenderEvent || Raised before and after drawing the world to the screen. − |- − | OnPreRenderGuiEvent<br />OnPostRenderGuiEvent || When a menu is open (<tt>Game1.activeClickableMenu != null</tt>), raised before and after drawing that menu to the screen. This includes the game's internal menus like the title screen. − |- − | OnPreRenderHudEvent<br />OnPostRenderHudEvent || Raised before and after drawing the HUD (item toolbar, clock, etc) to the screen. The HUD is available at this point, but not necessarily visible. (For example, the event is called even if a menu is open.) − |- − | Resize || Raised after the game window is resized. − |} − − ===Input events=== − <tt>InputEvents</tt> are raised when the player uses a controller, keyboard, or mouse. − − {{SMAPI upcoming|2.6|content='''Note:''' mods won't receive input sent to the chatbox, or the toggle-chatbox key.}} − − <table class="wikitable"> − <tr> − <th>event</th> − <th>summary</th> − </tr> − <tr> − <td>ButtonPressed<br />ButtonReleased</td> − <td>Raised after the player pressed/released a keyboard, mouse, or controller button. The event arguments include: − * the button pressed (as an <tt>SButton</tt> constant); − * whether the input counts as a 'click' (including the controller equivalent); − * the cursor position on the screen; − * the tile under the cursor; − * the 'grab tile' (i.e. the tile the game considers to be clicked). − − You can also... − * get the equivalent XNA button constants using <tt>button.TryGetKeyboard(…)</tt> and <tt>button.TryGetController(…)</tt>; − * prevent the game (but not other mods) from handling the input using <tt>eventArgs.SuppressButton()</tt>.</td> − </tr> − </table> − − ===Location events=== − <tt>LocationEvents</tt> are raised when the player transitions between game locations, a location is added or removed, or the objects in the current location change. − − '''In SMAPI 2.6-beta.5 or earlier:''' − :{| class="wikitable" − |- − ! event !! summary − |- − | CurrentLocationChanged || Raised after the player warps to a new location. Handlers are given the previous and new locations as arguments. − |- − | LocationObjectsChanged || Raised after the list of objects in the current location changes (e.g. an object is added or removed). Handlers are given the new list of objects as an argument. − |- − | LocationsChanged || Raised after a game location is added or removed. Handlers are passed the new list of locations as an argument. − |} − − {{SMAPI upcoming|2.6-beta.7}} − '''In SMAPI 2.6-beta.7 or later:''' − :{| class="wikitable" − |- − ! event !! summary − |- − | LocationsChanged || Raised after a game location is added or removed (including building interiors). Handlers are passed lists of added/removed locations. − |- − | BuildingsChanged || Raised after buildings is added/removed in any location. Handlers are given the location, and lists of added/removed buildings. − |- − | ObjectsChanged || Raised after objects are added/removed in any location (including building interiors). Handlers are given the location, and lists of added/removed objects. − |} − − ===Menu events=== − <tt>MenuEvents</tt> are raised when a game menu is opened or closed (including internal menus like the title screen). − − {| class="wikitable" − |- − ! event !! summary − |- − | MenuChanged || Raised after a game menu is opened or replaced with another menu. This event is not invoked when a menu is closed. Handlers are given the previous menu (if any) and new menu (if any). − |- − | MenuClosed || Raised after a game menu is closed. Handlers are given the previous menu. − |} − − ===Mine events=== − <tt>MineEvents</tt> are raised when something happens in [[The Mines]]. − − {| class="wikitable" − |- − ! event !! summary − |- − | MineLevelChanged || Raised after the player warps to a new level of the mine. Handlers are passed the previous and new mine level as arguments. − |} − − ===Multiplayer events=== − {{SMAPI upcoming|2.6}} − − <tt>MultiplayerEvents</tt> are raised during the multiplayer sync process. These are specialised events; most mods shouldn't use these directly. − − {| class="wikitable" − |- − ! event !! summary − |- − | BeforeMainSync<br />AfterMainSync || Raised before and after the game fetches data from other players and syncs the world to match. − |- − | BeforeMainBroadcast<br />AfterMainBroadcast || Raised before/after the game sends world data to other players. This event is raised for the main world broadcast, but a few specialised broadcasts (particularly sprite broadcasts) occur outside this event. − |} − − ===Player events=== − <tt>PlayerEvents</tt> are raised when the player data changes. − − {| class="wikitable" − |- − ! event !! summary − |- − | InventoryChanged || Raised after the current player's inventory changes in any way (added or removed item, sorted, etc). − |- − | LeveledUp || Raised after the current player levels up a skill. This happens as soon as they level up, not when the game notifies the player after their character goes to bed. − |- − | Warped || {{SMAPI upcoming|2.6-beta.7|content=Raised after the current player moves to a new location.}} − |} − − ===Save events=== − <tt>SaveEvents</tt> are raised when the player saves or loads the game. − − {| class="wikitable" − |- − ! event !! summary − |- − | BeforeCreate<br />AfterCreate || Raised before and after the game creates the save file (after the new-game intro). The save won't be written until all mods have finished handling this event. − |- − | AfterLoad || Raised after the player loads a saved game (or starts a new save). The world is ready for mods to modify at this point. − |- − | BeforeSave<br />AfterSave || Raised before and after the game updates the save file. Not raised for the initial creation. The save won't be written until all mods have finished handling this event. − |- − | AfterReturnToTitle || Raised after the player exits to the title screen. − |} − − ===Time events=== − <tt>TimeEvents</tt> are raised when the in-game date or time changes. − − {| class="wikitable" − |- − ! event !! summary − |- − | AfterDayStarted || Raised after the game begins a new day, including when loading a save. − |- − | TimeOfDayChanged || Raised after the in-game clock changes. − |} − − ===Specialised events=== − <tt>SpecialisedEvents</tt> serve specialised edge cases and should not be used by most mods. Mods using specialised events will be flagged in the SMAPI console as potentially impacting the game stability. − − {{collapse|expand for details|content= − <table class="wikitable"> − <tr> − <th>event</th> − <th>summary</th> − </tr> − <tr> − <td>UnvalidatedUpdateTick</td> − <td>Raised after the game updates its state (≈60 times per second), regardless of normal SMAPI validation. This event is not thread-safe and may be invoked while game logic is running asynchronously. Changes to game state in this method may crash the game or corrupt an in-progress save. '''Do not use this event unless you're fully aware of the context in which your code will be run. Using this event will trigger a warning in the SMAPI console.'''</td> − </tr> − </table> − }}
→Events: move to Modding:Modder Guide/APIs/Events
| Get information about loaded mods, and integrate with mods using mod-provided APIs.
| Get information about loaded mods, and integrate with mods using mod-provided APIs.
|}
|}
==Mod APIs==
==Mod APIs==