查看“模组:制作指南/APIs/Events”的源代码
←
模组:制作指南/APIs/Events
跳到导航
跳到搜索
因为以下原因,您没有权限编辑本页:
您所请求的操作仅限于该用户组的用户使用:
用户
您可以查看和复制此页面的源代码。
{{../../header}} {{翻译}} SMAPI 提供了几个 C#事件,这些事件使模组在某些事情发生时(例如,玩家放置一个对象时)做出响应,或者定期运行代码(例如,每个更新周期一次) ==常见问题== ===什么是事件(events) ?=== 事件使你可以在发生某些事情时运行代码。可以在引发“事件”(发生的情况)时添加任意数量的“事件处理程序”(调用方法)。 可以将事件和处理程序视为“when...then”语句: <pre> 存档已加载 <-- 事件 然后运行我的代码 <-- 事件处理程序 </pre> 有关详细信息,请参阅[https://learn.microsoft.com/zh-cn/dotnet/csharp/programming-guide/events/ C# 编程指南中的事件]中的“事件”。 ===如何使用它们?=== 通常将事件处理程序添加到 <samp>Entry</samp> 方法中,可以随时添加和删除它们。例如,在每天开始时打印一条消息。首先,从下面的列表中选择适当的事件 (<samp>[[#GameLoop.DayStarted|GameLoop.DayStarted]]</samp>), 然后添加一个事件处理程序,并在方法代码中执行以下操作: <syntaxhighlight lang="c#"> /// <summary>模组的主要入口点。</summary> public class ModEntry : Mod { /********** ** 公共方法 *********/ /// <summary>模组入口点,加载模组后自动调用</summary> /// <param name="helper">提供用于编写模组的简化API</param> public override void Entry(IModHelper helper) { // 事件 += 方法 helper.Events.GameLoop.DayStarted += this.OnDayStarted; } /********** ** 私有方法 *********/ /// <summary>在新的一天开始后调用的方法</summary> /// <param name="sender">事件对象</param> /// <param name="e">事件参数</param> private void OnDayStarted(object sender, DayStartedEventArgs e) { this.Monitor.Log("新的一天到来了!"); } } </syntaxhighlight> 提示:不需要记住方法参数。在 Visual Studio 中,输入 <code>helper.Events.GameLoop.SaveLoaded +=</code> 然后按 {{key|TAB}} 来自动生成方法 ===事件如何呈现到游戏中?=== 每次游戏计时(游戏更新其状态并呈现到屏幕时)都会引发事件,每秒60次。 一个事件可能会引发多次(例如,如果玩家同时按下两个键),但是大多数事件不会每秒引发60次(例如,玩家不太可能每秒按下60个按钮) 事件处理程序是“同步”运行的:游戏暂停时模组的代码不会运行,因此没有更改冲突的风险。由于代码运行非常迅速,因此除非你的代码异常缓慢,否则玩家不会注意到任何延迟。就是说,当使用诸如 <samp>UpdateTicked</samp> 或者 <samp>Rendered</samp> 应该缓存繁重的操作(例如加载资源),而不是在每个刻度中重复执行这些操作,以免影响性能。 ===如果模组更改了事件的发起?=== 事件根据游戏状态的快照引发,这通常是“但不一定”是当前游戏状态 例如,考虑这种情况: # 菜单 <samp>GameMenu</samp> 打开了 # SMAPI 引发 <samp>MenuChanged</samp> 事件,并且模组 A 和 B 正在监听 # 模组 A 接收了事件并关闭了菜单 # 模组 B 接收了事件 每个模组仍在处理菜单打开的 <samp>MenuChanged</samp> 事件,即使第一个模组已将菜单关闭。SMAPI 将在下一个刻度时为关闭的菜单引发一个新的 <samp>MenuChanged</samp> 事件 这很少会影响模组,但是如果你需要当前状态,则需要牢记 (例如考虑用 <samp>Game1.activeClickableMenu</samp> 代替 <samp>e.NewMenu</samp>) ==事件== 可用的事件记录在下面 ===显示=== <samp>this.Helper.Events.Display</samp> 具有链接到 UI 并绘制到屏幕的事件 {|class="wikitable" |- ! 事件 ! 描述 {{/event |group = Display |name = MenuChanged |desc = 在打开、关闭或替换游戏菜单后引发 |arg name 2 = <samp>e.OldMenu</samp> |arg type 2 = <samp>IClickableMenu</samp> |arg desc 2 = 旧的菜单实例 (如果没有,则为 <samp>null</samp>) |arg name 1 = <samp>e.NewMenu</samp> |arg type 1 = <samp>IClickableMenu</samp> |arg desc 1 = 新的菜单实例 (如果没有,则为 <samp>null</samp> ) }} {{/event |group = Display |name = Rendering |desc = 打开 sprite batch 后,在游戏将任何内容绘制到屏幕上之前就引发。 The sprite batch may be closed and reopened multiple times after this event is called, but it's only raised once per draw tick. 此事件对于在屏幕上绘制没有用, since the game will draw over it. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = Rendered |desc = Raised after the game draws to the sprite patch in a draw tick, just before the final sprite batch is rendered to the screen. Since the game may open/close the sprite batch multiple times in a draw tick, the sprite batch may not contain everything being drawn and some things may already be rendered to the screen. Content drawn to the sprite batch at this point will be drawn over all vanilla content (including menus, HUD, and cursor). |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderingWorld |desc = Raised before the game world is drawn to the screen. This event isn't useful for drawing to the screen, since the game will draw over it. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderedWorld |desc = Raised after the game world is drawn to the sprite patch, before it's rendered to the screen. Content drawn to the sprite batch at this point will be drawn over the world, but under any active menu, HUD elements, or cursor. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderingActiveMenu |desc = 当一个菜单被打开时 (<samp>Game1.activeClickableMenu != null</samp>), 在将该菜单绘制到屏幕上之前触发。这包括游戏的内部菜单,例如进入游戏时的主菜单。Content drawn to the sprite batch at this point will appear under the menu. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderedActiveMenu |desc = When a menu is open (<samp>Game1.activeClickableMenu != null</samp>), raised after that menu is drawn to the sprite batch but before it's rendered to the screen. Content drawn to the sprite batch at this point will appear over the menu and menu cursor. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderingHud |desc = Raised before drawing the HUD (item toolbar, clock, etc) to the screen. The vanilla HUD may be hidden at this point (''e.g.,'' because a menu is open). Content drawn to the sprite batch at this point will appear under the HUD. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = RenderedHud |desc = Raised after drawing the HUD (item toolbar, clock, etc) to the sprite batch, but before it's rendered to the screen. The vanilla HUD may be hidden at this point (''e.g.,'' because a menu is open). Content drawn to the sprite batch at this point will appear over the HUD. |arg name 1 = <samp>e.SpriteBatch</samp> |arg type 1 = <samp>SpriteBatch</samp> |arg desc 1 = The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch. }} {{/event |group = Display |name = WindowResized |desc = Raised after the game window is resized. |arg name 1 = <samp>e.OldSize</samp> |arg type 1 = <samp>Point</samp> |arg desc 1 = The previous window width (<samp>e.OldSize.X</samp>) and height (<samp>e.OldSize.Y</samp>). |arg name 2 = <samp>e.NewSize</samp> |arg type 2 = <samp>Point</samp> |arg desc 2 = The new window width (<samp>e.NewSize.X</samp>) and height (<samp>e.NewSize.Y</samp>). }} |} ===游戏循环=== <samp>this.Helper.Events.GameLoop</samp> has events linked to the game's update loop. The update loop runs roughly ≈60 times/second to run game logic like state changes, action handling, etc. These are often useful, but you should consider semantic events like <samp>Input</samp> where applicable. {|class="wikitable" |- ! event ! summary {{/event |group = GameLoop |name = GameLaunched |desc = Raised after the game is launched, right before the first update tick. This happens once per game session (unrelated to loading saves). All mods are loaded and initialised at this point, so this is a good time to set up mod integrations. }} {{/event |group = GameLoop |name = UpdateTicking, UpdateTicked |desc = Raised before/after the game state is updated (≈60 times per second). |arg name 1 = <samp>e.Ticks</samp> |arg type 1 = <samp>int</samp> |arg desc 1 = The number of ticks elapsed since the game started, including the current tick. |arg name 2 = <samp>e.IsOneSecond</samp> |arg type 2 = <samp>bool</samp> |arg desc 2 = Whether <samp>e.TicksElapsed</samp> is a multiple of 60, which happens approximately once per second. |arg name 3 = <samp>e.IsMultipleOf(int number)</samp> |arg type 3 = ''method'' returns <samp>bool</samp> |arg desc 3 = Whether <samp>e.TicksElapsed</samp> is a multiple of the given number. This is mainly useful if you want to run logic intermittently (''e.g.,'' <code>e.IsMultipleOf(30)</code> for every half-second). }} {{/event |group = GameLoop |name = OneSecondUpdateTicking, OneSecondUpdateTicked |desc = Raised before/after the game state is updated, once per second. |arg name 1 = <samp>e.Ticks</samp> |arg type 1 = <samp>int</samp> |arg desc 1 = The number of ticks elapsed since the game started, including the current tick. |arg name 3 = <samp>e.IsMultipleOf(int number)</samp> |arg type 3 = ''method'' returns <samp>bool</samp> |arg desc 3 = Whether <samp>e.TicksElapsed</samp> is a multiple of the given number. This is mainly useful if you want to run logic intermittently (''e.g.,'' <code>e.IsMultipleOf(120)</code> for every two seconds). }} {{/event |group = GameLoop |name = SaveCreating, SaveCreated |desc = Raised before/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. This is a somewhat specialised event, since the world isn't fully initialised at this point; in most cases you should use [[#GameLoop.DayStarted|<samp>DayStarted</samp>]], [[#GameLoop.Saving|<samp>Saving</samp>]], [[#GameLoop.Saved|<samp>Saved</samp>]] instead. }} {{/event |group = GameLoop |name = Saving, Saved |desc = Raised before/after the game writes data to save file (except [[#GameLoop.SaveCreating|the initial save creation]]). The save won't be written until all mods have finished handling this event. This is also raised for farmhands in multiplayer. }} {{/event |group = GameLoop |name = SaveLoaded |desc = Raised after loading a save (including the first day after creating a new save), or connecting to a multiplayer world. This happens right before <samp>DayStarted</samp>; at this point the save file is read and <samp>[[Modding:Modder Guide/APIs/Utilities#Context|Context.IsWorldReady]]</samp> is true. This event isn't raised after saving; if you want to do something at the start of each day, see [[#GameLoop.DayStarted|<samp>DayStarted</samp>]] instead. }} {{/event |group = GameLoop |name = DayStarted |desc = Raised after a new in-game day starts, or after connecting to a multiplayer world. Everything has already been initialised at this point. (To run code before the game sets up the day, see [[#GameLoop.DayEnding|<samp>DayEnding</samp>]] instead.) }} {{/event |group = GameLoop |name = DayEnding |desc = Raised before the game ends the current day. This happens before it starts setting up the next day and before [[#GameLoop.Saving|<samp>Saving</samp>]]. }} {{/event |group = GameLoop |name = TimeChanged |desc = Raised after the in-game clock time changes, which happens in intervals of ten in-game minutes. |arg name 1 = <samp>e.OldTime</samp> |arg type 1 = <samp>int</samp> |arg desc 1 = The previous time of day in 24-hour notation (like 1600 for 4pm). The clock time resets when the player sleeps, so 2am (before sleeping) is 2600. |arg name 2 = <samp>e.NewTime</samp> |arg type 2 = <samp>int</samp> |arg desc 2 = The current time of day in 24-hour notation (like 1600 for 4pm). The clock time resets when the player sleeps, so 2am (before sleeping) is 2600. }} {{/event |group = GameLoop |name = ReturnedToTitle |desc = Raised after the game returns to the title screen. }} |} ===输入=== <samp>this.Helper.Events.Input</samp> has events raised when the player uses a controller, keyboard, or mouse in some way. They can be used with the [[../Input|input API]] to access more info or suppress input. {|class="wikitable" |- ! event ! summary {{/event |group = Input |name = ButtonsChanged |desc = Raised after the player pressed/released any buttons on the keyboard, mouse, or controller. This includes mouse clicks. If the player pressed/released multiple keys at once, this is only raised once. |arg name 1 = <samp>e.Pressed</samp> |arg type 1 = [[Modding:Modder Guide/APIs/Input#SButton|<samp>SButton[]</samp>]] |arg desc 1 = The buttons that were pressed since the previous tick. |arg name 2 = <samp>e.Held</samp> |arg type 2 = [[Modding:Modder Guide/APIs/Input#SButton|<samp>SButton[]</samp>]] |arg desc 2 = The buttons that were held since the previous tick. |arg name 3 = <samp>e.Released</samp> |arg type 3 = [[Modding:Modder Guide/APIs/Input#SButton|<samp>SButton[]</samp>]] |arg desc 3 = The buttons that were released since the previous tick. |arg name 4 = <samp>e.Cursor</samp> |arg type 4 = [[Modding:Modder Guide/APIs/Input#Check cursor position|<samp>ICursorPosition</samp>]] |arg desc 4 = The cursor position and grab tile. '''Note:''' mods won't receive input sent to the chatbox. }} {{/event |group = Input |name = ButtonPressed, ButtonReleased |desc = Raised after the player pressed/released a keyboard, mouse, or controller button. This includes mouse clicks. If the player pressed/released multiple keys at once, this is raised for each button pressed. |arg name 1 = <samp>e.Button</samp> |arg type 1 = [[Modding:Modder Guide/APIs/Input#SButton|<samp>SButton</samp>]] |arg desc 1 = The button pressed or released. |arg name 2 = <samp>e.Cursor</samp> |arg type 2 = [[Modding:Modder Guide/APIs/Input#Check cursor position|<samp>ICursorPosition</samp>]] |arg desc 2 = The cursor position and grab tile. |arg name 3 = <samp>e.IsDown</samp> |arg type 3 = ''method'' returns <samp>bool</samp> |arg desc 3 = Indicates whether a given button is currently pressed. |arg name 4 = <samp>e.IsSuppressed</samp> |arg type 4 = ''method'' returns <samp>bool</samp> |arg desc 4 = A method which indicates whether a given button was suppressed by a mod, so the game itself won't see it. '''Note:''' mods won't receive input sent to the chatbox. }} {{/event |group = Input |name = CursorMoved |desc = Raised after the player moves the in-game cursor. |arg name 1 = <samp>e.OldPosition</samp> |arg type 1 = [[Modding:Modder Guide/APIs/Input#Check cursor position|ICursorPosition]] |arg desc 1 = The previous cursor position and grab tile. |arg name 2 = <samp>e.NewPosition</samp> |arg type 2 = [[Modding:Modder Guide/APIs/Input#Check cursor position|ICursorPosition]] |arg desc 2 = The current cursor position and grab tile. }} {{/event |group = Input |name = MouseWheelScrolled |desc = Raised after the player scrolls the mouse wheel. |arg name 1 = <samp>e.Position</samp> |arg type 1 = [[Modding:Modder Guide/APIs/Input#Check cursor position|ICursorPosition]] |arg desc 1 = The current cursor position and grab tile. |arg name 2 = <samp>e.Delta</samp> |arg type 2 = <samp>int</samp> |arg desc 2 = The amount by which the mouse wheel was scrolled since the last update. |arg name 3 = <samp>e.OldValue</samp><br /><samp>e.NewValue</samp> |arg type 3 = <samp>int</samp> |arg desc 3 = The previous and current scroll value, cumulative since the game started. Mods should generally use <samp>e.Delta</samp> instead. }} |} ===多人=== <samp>this.Helper.Events.Multiplayer</samp> has events raised for multiplayer messages and connections. {|class="wikitable" |- ! event ! summary {{/event |group = Multiplayer |name = PeerContextReceived |desc = Raised after the mod context for a player is received. The event is raised for any player (whether host or farmhand), including when the connecting player doesn't have SMAPI installed. This is the earliest point where messages can be sent to the player via SMAPI. This happens immediately before the game approves the connection, so the player doesn't exist in the game yet. When connecting to the host, contextual fields like <samp>Game1.IsMasterGame</samp> or <samp>Context.IsMultiplayer</samp> may not be set yet; you can check <samp>e.Peer.IsHost</samp> to know whether the current player is a farmhand, since the host context will always be received first. Assuming another mod doesn't block the connection, the connection will be approved on the next tick. |arg name 1 = <samp>e.Peer</samp> |arg type 1 = <samp>IMultiplayerPeer</samp> |arg desc 1 = The peer whose context was received (see [[Modding:Modder Guide/APIs/Multiplayer#Get connected player info|Multiplayer#Get connected player info]]). }} {{/event |group = Multiplayer |name = PeerConnected |desc = Raised after a connection from another player is approved by the game. The event is raised for any player (whether host or farmhand), including when the connecting player doesn't have SMAPI installed. This happens after <samp>PeerContextReceived</samp>. The player is connected to the game at this point, so methods like <samp>Game1.server.kick</samp> will work. |arg name 1 = <samp>e.Peer</samp> |arg type 1 = <samp>IMultiplayerPeer</samp> |arg desc 1 = The peer who connected (see [[Modding:Modder Guide/APIs/Multiplayer#Get connected player info|Multiplayer#Get connected player info]]). }} {{/event |group = Multiplayer |name = ModMessageReceived |desc = Raised after [[Modding:Modder Guide/APIs/Multiplayer#Send messages|a mod message]] is received over the network. |arg name 1 = <samp>e.FromPlayerID</samp> |arg type 1 = <samp>long</samp> |arg desc 1 = The unique ID of the player from whose computer the message was sent. |arg name 2 = <samp>e.FromModID</samp> |arg type 2 = <samp>string</samp> |arg desc 2 = The unique ID of the mod which sent the message. |arg name 3 = <samp>e.Type</samp> |arg type 3 = <samp>string</samp> |arg desc 3 = A message type which you can use to decide whether it's the one you want to handle. This isn't necessarily globally unique, so you should also check the <samp>FromModID</samp> field. |arg name 4 = <samp>e.ReadAs<TModel>()</samp> |arg type 4 = ''method'' returns <samp>TModel</samp> |arg desc 4 = Read the underlying message data into the given model type (like <code>e.ReadAs<MyMessageClass>()</code> or <code>e.ReadAs<string>()</code>). This will return a new instance each time. }} {{/event |group = Multiplayer |name = PeerDisconnected |desc = Raised after the connection to a player is severed. |arg name 1 = <samp>e.Peer</samp> |arg type 1 = <samp>IMultiplayerPeer</samp> |arg desc 1 = The peer whose connection was severed (see [[Modding:Modder Guide/APIs/Multiplayer#Get connected player info|Multiplayer#Get connected player info]]). }} |} ===玩家=== <samp>this.Helper.Events.Player</samp> has events raised when the player data changes. '''Currently these events are only raised for the current player. That will likely change in a future version, so make sure to check <samp>e.IsLocalPlayer</samp> if you only want to handle the current player.''' {|class="wikitable" |- ! event ! summary {{/event |group = Player |name = InventoryChanged |desc = Raised after items are added or removed from the player inventory. |arg name 1 = <samp>e.Player</samp> |arg type 1 = <samp>Farmer</samp> |arg desc 1 = The player whose inventory changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<Item></samp> |arg desc 2 = The added item stacks. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<Item></samp> |arg desc 3 = The removed item stacks. |arg name 4 = <samp>e.QuantityChanged</samp> |arg type 4 = <samp>IEnumerable<ItemStackSizeChange></samp> |arg desc 4 = The item stacks whose quantity changed. Each <samp>ItemStackSizeChange</samp> instance includes <samp>Item</samp> (the affected item stack), <samp>OldSize</samp> (the previous stack size), and <samp>NewSize</samp> (the new stack size). |arg name 5 = <samp>e.IsLocalPlayer</samp> |arg type 5 = <samp>bool</samp> |arg desc 5 = Whether the affected player is the local one. }} {{/event |group = Player |name = LevelChanged |desc = Raised after a player's skill level changes. When the player levels up normally, this is raised immediately (not when the game notifies the player after they go to bed). |arg name 1 = <samp>e.Player</samp> |arg type 1 = <samp>Farmer</samp> |arg desc 1 = The player whose skill level changed. |arg name 2 = <samp>e.Skill</samp> |arg type 2 = <samp>SkillType</samp> |arg desc 2 = The skill whose level changed. This is a constant like <code>SkillType.Combat</code>, which can be converted to the game's internal skill ID using <code>(int)e.Skill</code>. |arg name 3 = <samp>e.OldLevel</samp> |arg type 3 = <samp>int</samp> |arg desc 3 = The player's previous level for that skill. |arg name 4 = <samp>e.NewLevel</samp> |arg type 4 = <samp>int</samp> |arg desc 4 = The player's new level for that skill. |arg name 5 = <samp>e.IsLocalPlayer</samp> |arg type 5 = <samp>bool</samp> |arg desc 5 = Whether the affected player is the local one. }} {{/event |group = Player |name = Warped |desc = Raised after the current player moves to a new location. |arg name 1 = <samp>e.Player</samp> |arg type 1 = <samp>Farmer</samp> |arg desc 1 = The player who warped to a new location. |arg name 2 = <samp>e.OldLocation</samp> |arg type 2 = <samp>GameLocation</samp> |arg desc 2 = The player's previous location. |arg name 3 = <samp>e.NewLocation</samp> |arg type 3 = <samp>GameLocation</samp> |arg desc 3 = The player's new location. |arg name 4 = <samp>e.IsLocalPlayer</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether the affected player is the local one. }} |} ===世界=== <samp>this.Helper.Events.World</samp> has events raised when the in-game world changes in some way. {|class="wikitable" |- ! event ! summary {{/event |group = World |name = LocationListChanged |desc = Raised after a game location is added or removed (including building interiors). |arg name 1 = <samp>e.Added</samp> |arg type 1 = <samp>IEnumerable<GameLocation></samp> |arg desc 1 = A list of locations added since the last update tick. |arg name 2 = <samp>e.Removed</samp> |arg type 2 = <samp>IEnumerable<GameLocation></samp> |arg desc 2 = A list of locations removed since the last update tick. }} {{/event |group = World |name = BuildingListChanged |desc = Raised after buildings are added/removed in any location. This event isn't raised for buildings already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added.OfType<BuildableGameLocation>()</samp> → <samp>buildings</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<Building></samp> |arg desc 2 = A list of buildings added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<Building></samp> |arg desc 3 = A list of buildings removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} {{/event |group = World |name = ChestInventoryChanged |desc = Raised after items are added or removed from a chest's inventory. |arg name 1 = <samp>e.Chest</samp> |arg type 1 = <samp>Chest</samp> |arg desc 1 = The chest whose inventory changed. |arg name 2 = <samp>e.Location</samp> |arg type 2 = <samp>Location</samp> |arg desc 2 = The location containing the chest. |arg name 3 = <samp>e.Added</samp> |arg type 3 = <samp>IEnumerable<Item></samp> |arg desc 3 = The added item stacks. |arg name 4 = <samp>e.Removed</samp> |arg type 4 = <samp>IEnumerable<Item></samp> |arg desc 4 = The removed item stacks. |arg name 5 = <samp>e.QuantityChanged</samp> |arg type 5 = <samp>IEnumerable<ItemStackSizeChange></samp> |arg desc 5 = The item stacks whose quantity changed. Each <samp>ItemStackSizeChange</samp> instance includes <samp>Item</samp> (the affected item stack), <samp>OldSize</samp> (the previous stack size), and <samp>NewSize</samp> (the new stack size). }} {{/event |group = World |name = DebrisListChanged |desc = Raised after debris is added/removed in any location (including dropped or spawned floating items). This event isn't raised for debris already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added</samp> → <samp>debris</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<Debris></samp> |arg desc 2 = A list of debris added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<Debris></samp> |arg desc 3 = A list of debris removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} {{/event |group = World |name = LargeTerrainFeatureListChanged |desc = Raised after large terrain features (like bushes) are added/removed in any location. This event isn't raised for large terrain features already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added</samp> → <samp>largeTerrainFeatures</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<LargeTerrainFeature></samp> |arg desc 2 = A list of large terrain features added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<LargeTerrainFeature></samp> |arg desc 3 = A list of large terrain features removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} {{/event |group = World |name = NpcListChanged |desc = Raised after NPCs are added/removed in any location (including villagers, horses, Junimos, monsters, and pets). This event isn't raised for characters already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added</samp> → <samp>characters</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<NPC></samp> |arg desc 2 = A list of NPCs added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<NPC></samp> |arg desc 3 = A list of NPCs removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} {{/event |group = World |name = ObjectListChanged |desc = Raised after objects are added/removed in any location (including machines, furniture, fences, etc). For floating items, see <samp>DebrisListChanged</samp>. This event isn't raised for objects already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added</samp> → <samp>objects</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<KeyValuePair<Vector2, Object>></samp> |arg desc 2 = A list of [[Modding:Modder Guide/Game Fundamentals#Tiles|tile coordinate]] + object pairs added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<KeyValuePair<Vector2, Object>></samp> |arg desc 3 = A list of [[Modding:Modder Guide/Game Fundamentals#Tiles|tile coordinate]] + object pairs removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} {{/event |group = World |name = TerrainFeatureListChanged |desc = Raised after terrain features are added/removed in any location (including trees, hoed dirt, and flooring). For bushes, see <samp>LargeTerrainFeatureListChanged</samp>. This event isn't raised for terrain features already present when a location is added. If you need to handle those too, use [[#World.LocationListChanged|<samp>LocationListChanged</samp>]] and check <samp>e.Added</samp> → <samp>terrainFeatures</samp>. |arg name 1 = <samp>e.Location</samp> |arg type 1 = <samp>GameLocation</samp> |arg desc 1 = The location which changed. |arg name 2 = <samp>e.Added</samp> |arg type 2 = <samp>IEnumerable<KeyValuePair<Vector2, TerrainFeature>></samp> |arg desc 2 = A list of [[Modding:Modder Guide/Game Fundamentals#Tiles|tile coordinate]] + terrain feature pairs added since the last update tick. |arg name 3 = <samp>e.Removed</samp> |arg type 3 = <samp>IEnumerable<KeyValuePair<Vector2, TerrainFeature>></samp> |arg desc 3 = A list of [[Modding:Modder Guide/Game Fundamentals#Tiles|tile coordinate]] + terrain feature pairs removed since the last update tick. |arg name 4 = <samp>e.IsCurrentLocation</samp> |arg type 4 = <samp>bool</samp> |arg desc 4 = Whether <samp>e.Location</samp> is the location containing the local player. }} |} ===特殊=== <samp>this.Helper.Events.Specialised</samp> 针对特殊情况的事件. 大多数模组不应使用这些功能 {|class="wikitable" |- ! event ! summary {{/event |group = Specialised |name = LoadStageChanged |desc = Raised when the low-level stage in the game's loading process has changed, for mods which need to run code at specific points in the loading process. The available stages or when they happen might change without warning in future versions (''e.g.,'' due to changes in the game's load process), so '''mods using this event are more likely to break or have bugs'''. Most mods should use the [[#Game loop|game loop events]] instead. |arg name 1 = <samp>e.NewStage</samp> |arg type 1 = <samp>LoadStage</samp> |arg desc 1 = The new load stage. The possible values are... * <code>None</code>: a save is not loaded or loading. (For example, the player is on the title screen.) * When creating a new save slot: ** <code>CreatedBasicInfo</code>: the game has initialised the basic save info. ** <code>CreatedInitialLocations</code>: the game has added the location instances, but hasn't fully initialized them yet. ** <code>CreatedLocations</code>: the game has initialised the in-game locations. ** <code>CreatedSaveFile</code>: the game has created the physical save files. * When loading an existing save slot: ** <code>SaveParsed</code>: the game has read the raw save data into <samp>StardewValley.SaveGame.loaded</samp>. Not applicable when connecting to a multiplayer host. This is equivalent to <samp>StardewValley.SaveGame.getLoadEnumerator</samp> value 20. ** <code>SaveLoadedBasicInfo</code>: the game has applied the basic save info (including player data). Not applicable when connecting to a multiplayer host. Note that some basic info (like daily luck) is not initialised at this point. This is equivalent to <samp>StardewValley.SaveGame.getLoadEnumerator</samp> value 36. ** <code>SaveAddedLocations</code>: the game has added the location instances to the game, but hasn't restored their save data yet. ** <code>SaveLoadedLocations</code>: the game has restored the in-game location data. Not applicable when connecting to a multiplayer host. This is equivalent to <samp>StardewValley.SaveGame.getLoadEnumerator</samp> value 50. * <code>Preloaded</code>: the final metadata has been loaded from the save file. This happens before the game applies problem fixes, checks for achievements, starts music, etc. Not applicable when connecting to a multiplayer host. * <code>Loaded</code>: the save is fully loaded, but the world may not be fully initialised yet. * <code>Ready</code>: the save is fully loaded, the world has been initialised, and [[Modding:Modder Guide/APIs/Utilities#Context|<samp>Context.IsWorldReady</samp>]] is now true. * <code>ReturningToTitle</code>: The game is exiting the loaded save and returning to the title screen. This happens before it returns to title; the stage ''after'' it returns to title is <code>None</code>. |arg name 2 = <samp>e.OldStage</samp> |arg type 2 = <samp>LoadStage</samp> |arg desc 2 = The previous load stage. See comments for <samp>e.NewStage</samp>. }} {{/event |group = Specialised |name = UnvalidatedUpdateTicking, UnvalidatedUpdateTicked |desc = Raised before/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.''' |arg name 1 = <samp>e.Ticks</samp> |arg type 1 = <samp>int</samp> |arg desc 1 = The number of ticks elapsed since the game started, including the current tick. |arg name 2 = <samp>e.IsOneSecond</samp> |arg type 2 = <samp>bool</samp> |arg desc 2 = Whether <samp>e.TicksElapsed</samp> is a multiple of 60, which happens approximately once per second. |arg name 3 = <samp>e.IsMultipleOf(int number)</samp> |arg type 3 = ''method'' returns <samp>bool</samp> |arg desc 3 = Whether <samp>e.TicksElapsed</samp> is a multiple of the given number. This is mainly useful if you want to run logic intermittently (''e.g.,'' <code>e.IsMultipleOf(30)</code> for every half-second). }} |} ==进阶== ===变化监控=== You may want to handle a change that doesn't have its own event (''e.g.,'' an in-game event ends, a letter is added to the mailbox, etc). You can usually do that by handling a general event like [[#GameLoop.UpdateTicked|<samp>UpdateTicked</samp>]], and detecting when the value(s) you're watching changed. For example, here's a complete mod which logs a message when an in-game event ends: <syntaxhighlight lang="c#"> /// <summary>The main entry point for the mod.</summary> public class ModEntry : Mod { /********* ** Fields *********/ /// <summary>The in-game event detected on the last update tick.</summary> private Event LastEvent; /********* ** Public methods *********/ /// <summary>The mod entry point, called after the mod is first loaded.</summary> /// <param name="helper">Provides simplified APIs for writing mods.</param> public override void Entry(IModHelper helper) { helper.Events.GameLoop.UpdateTicked += this.OnUpdateTicked; } /********* ** Private methods *********/ /// <summary>The method invoked when the game updates its state.</summary> /// <param name="sender">The event sender.</param> /// <param name="e">The event arguments.</param> private void OnUpdateTicked(object sender, EventArgs e) { if (this.LastEvent != null && Game1.CurrentEvent == null) this.Monitor.Log($"Event {this.LastEvent.id} just ended!"); this.LastEvent = Game1.CurrentEvent; } } </syntaxhighlight> ===自定义优先级=== SMAPI calls event handlers in the same order they're registered by default, so the first event handler registered is the first to receive the event each time. This isn't always predictable, since it depends on mod load order and when each mod registers their handlers. This order is also an implementation detail, so it's not guaranteed. If you need more control over the order, you can specify an event priority using the <code>[EventPriority]</code> attribute: <samp>Low</samp> (after most handlers), <samp>Default</samp>, <samp>High</samp> (before most handlers), or a custom value (''e.g.,'' <samp>High + 1</samp> is higher priority than <samp>High</samp>). '''You should only do this if strictly needed'''; depending on event handler order between mods is fragile (''e.g.,'' the other mod might change its priority too). <syntaxhighlight lang="c#"> /// <summary>The main entry point for the mod.</summary> public class ModEntry : Mod { /********* ** Public methods *********/ /// <summary>The mod entry point, called after the mod is first loaded.</summary> /// <param name="helper">Provides simplified APIs for writing mods.</param> public override void Entry(IModHelper helper) { helper.Events.GameLoop.UpdateTicked += this.OnUpdateTicked; } /********* ** Private methods *********/ /// <summary>The method invoked when the game updates its state.</summary> /// <param name="sender">The event sender.</param> /// <param name="e">The event arguments.</param> [EventPriority(EventPriority.High)] private void OnUpdateTicked(object sender, EventArgs e) { this.Monitor.Log("Update!"); } } </syntaxhighlight> [[en:Modding:Modder Guide/APIs/Events]]
该页面使用的模板:
Template:Key
(
查看源代码
)
Template:Quote
(
查看源代码
)
Template:Quote/styles.css
(
查看源代码
)
Template:翻译
(
查看源代码
)
模组:制作指南/APIs/Events/event
(
查看源代码
)
模组:制作指南/header
(
查看源代码
)
返回至
模组:制作指南/APIs/Events
。
导航菜单
个人工具
创建账户
登录
名字空间
模组
讨论
不转换
不转换
简体
繁體
大陆简体
香港繁體
澳門繁體
大马简体
新加坡简体
台灣正體
视图
阅读
查看源代码
查看历史
更多
搜索
导航
首页
最近更改
未翻译的页面
帮助:编辑入门
随机页面
官方链接
官方网站
官方论坛
官方商品
Discord
Reddit
工具
链入页面
相关更改
上传文件
特殊页面
页面信息