模组:製作指南/遊戲基本架構
製作SMAPI模組 
← 模組:目錄
本頁面將簡單闡述部分遊戲內的概念以幫助您製作模組。配合常見問題食用體驗更佳。
一些概念
圖塊 (Tiles)
星露谷是由一個個圖塊組成的。我們又為它們定義了自己的坐標，如 (0, 0)表示左上角。橫坐標越往右值越大，縱坐標越往下值越大。
位置 (Positions)
| 定位方式 | 參照點 | 解釋 |
|---|---|---|
| 圖塊坐標 (tile position) | 地圖左上角 | 以單元格為單位。通常用於物品放置，如：location.Objects。 |
| 絕對坐標 (absolute position) | 地圖左上角 | 以像素為單位。用於更精確的測量，如：NPC的位置。 |
| 相對於屏幕的坐標 (screen position) | 可見(visible) 的屏幕的左上角 | 以像素為單位。通常用於繪製。 |
換算：
| A → B | 公式 | ||
|---|---|---|---|
| absolute | → | screen | x - Game1.viewport.X, y - Game1.viewport.Y
|
| absolute | → | tile | x / Game1.tileSize, y / Game1.tileSize
|
| screen | → | absolute | x + Game1.viewport.X, y + Game1.viewport.Y
|
| screen | → | tile | (x + Game1.viewport.X) / Game1.tileSize, (y + Game1.viewport.Y) / Game1.tileSize
|
| tile | → | absolute | x * Game1.tileSize, y * Game1.tileSize
|
| tile | → | screen | (x * Game1.tileSize) - Game1.viewport.X, (y * Game1.tileSize) - Game1.viewport.Y
|
Net類型的數據 (Net fields)
在源碼中，有這樣一種特殊的類型，它們都以Net作為前綴命名，因此得名net類型 (net type)。 在聯機模式中，遊戲正是通過這些net類型實現了在玩家之間同步數據。 每隔一段時間，遊戲便會從Game1.netWorldState儘可能收集所有net數據，來與其他玩家同步。這表明，很多因模組做出的改變會自動被遊戲同步。
儘管net類型自帶隱式轉換，如：bool x = new NetBool(true);，但並不穩定，很可能會跟你所想達成的目標有出入，如：item?.category == null和item?.category != null 有可能會同時為true。
因此，請避免用net類型的隱式轉換。具體如何拿到對應的值見下表：
| net類型 | 說明 |
|---|---|
| NetBool NetColor NetFloat NetInt NetPoint NetString |
這些屬於簡單的net類型。通過field.Value拿到對應值。 |
| NetCollection<T> NetList<T> NetObjectList<T> |
T的集合。直接遍歷 foreach (T value in field)。
|
| NetLongDictionary<TValue, TNetValue> NetPointDictionary<TValue, TNetValue> NetVector2Dictionary<TValue, TNetValue> |
將Long, Point, 或Vector2 類型的鍵映射至 TValue (原類型) 和 TNetValue (用於同步的net類型)。遍歷鍵值對，如：foreach (KeyValuePair<Long, TValue> pair in field.Pairs)。
|
縮放 (Zoom level)
玩家可以設置縮放等級，從75%到200%。這會影響屏幕上顯示的像素大小。
| 縮放至最小 (75%) | 縮放至最大 (200%) |
|---|---|
|
|
對於SMAPI模組的影響
縮放等級儲存在Game1.options.zoomLevel中。遊戲會自動調整坐標繪製大小，很少有情況需要你親自調整。萬一有，你可以position * (1f / Game1.options.zoomLevel)手動調。
UI縮放 (UI Scaling)
在1.5版本中，遊戲加入了縮放UI的功能。這是一個獨立於上一節的縮放的新功能，特別用於縮放用戶界面，最小75%，最大150%。
| UI最小顯示 (75%) | UI最大顯示 (150%) |
|---|---|
|
|
對於SMAPI模組的影響
遊戲有兩種縮放模式，UI 和 non-UI。當前模式儲存在Game1.uiMode中。不要將兩種模式混淆，這會帶來複雜的計算。
下表是遊戲使用兩種縮放模式的不同情景：
| 情景 | 縮放模式 |
|---|---|
| 菜單 (clickable menus) | UI模式 (通常) |
| HUD消息 | UI模式 |
| RenderingActiveMenu事件 RenderedActiveMenu事件 |
UI模式 |
| Rendering事件 Rendered事件 |
取決於具體上下文 |
| draw方法 | non-UI模式 |
| tile (non-pixel) coordinates | 不受UI縮放影響 |
當遊戲不在UI模式中，而你又想繪製UI時，請手動設置：
Game1.game1.InUIMode(() =>
{
// ...
});
在UI模式中，Game1.viewport通常可以替換成Game1.uiViewport。... // 未翻譯
主要的類
Game1
遊戲主要邏輯。 下面是一些重要的成員：
| 欄位、屬性 | 類型 | 描述 |
|---|---|---|
| Game1.player | Farmer | 當前玩家。 |
| Game1.currentLocation | GameLocation | 當前玩家所在的地點。 對於聯機中客機玩家，在地點變化時可能為null。 |
| Game1.locations | IList<GameLocation> | 所有地點。對於聯機中客機玩家，請使用SMAPI的GetActiveLocations方法代替。 |
| Game1.timeOfDay Game1.dayOfMonth Game1.currentSeason Game1.year |
int int string int |
當前時間、日期、季節、年份。另見SMAPI的日期工具類。 |
| Game1.itemsToShip | IList<Item> | 不要用這個，這是存檔邏輯的一部分。請用Game1.getFarm().getShippingBin(Farmer)。 |
| Game1.activeClickableMenu | IClickableMenu | 當前顯示的菜單。 |
GameLocation
表示地點，內有地圖、物品、角色、動植物等等數據。下表是一些重要的成員：
| 欄位、屬性 | 類型 | 描述 |
|---|---|---|
| Name | string | 唯一名稱。(這對於建築室內並不唯一，見uniqueName。) |
| IsFarm | bool | 是否為農場（農場內可種植作物）。 |
| IsGreenhouse | bool | 是否為溫室（溫室內可種植作物，且全年可生長）。 |
| IsOutdoors | bool | 是否為室外。 |
| characters | NetCollection of NPC | 該地點中的村民、寵物、馬、怪物。 |
| critters (private) | List of Critter | 該地點中暫時的鳥、松鼠等等，用於襯托景色。 |
| debris | NetCollection of Debris | 掉落物（漂浮的物品）。 |
| farmers | FarmerCollection | 該地點中的玩家。 |
| Objects | OverlaidDictionary | 該地點中所有物品。(OverlaidDictionary實際上是一個NetVector2Dictionary，並額外增加了show certain quest items over pre-existing objects 的邏輯。) |
| terrainFeatures | NetVector2Dictionary of TerrainFeature | 該地點中的樹、果樹、草、泥土地（其中包括農作物）、地板等等。 |
| waterTiles | bool[,] | 一個多維數組表示地圖圖塊是否為代表河/湖。如：if (location.waterTiles[10, 20])將檢查坐標為(10, 20)的圖塊。
|
BuildableGameLocation
GameLocation的子類。表示支持建造建築的地點。原版遊戲中，只有Farm是BuildableGameLocation。下面是一些重要的成員：
| 欄位 | 類型 | 描述 |
|---|---|---|
| buildings | NetCollection of Building | 該地點中的建築。 |
Farm
GameLocation和BuildableGameLocation的子類。玩家可在農場中養動物、種莊稼。原版遊戲中，Farm類型的實例地點只有一個（Game1.getFarm();）。下面是一些重要的成員：
| 欄位、屬性 | 類型 | 描述 |
|---|---|---|
| animals | NetLongDictionary of FarmAnimal | The farm animals currently in the location. |
| resourceClumps | NetCollection of ResourceClump | 該地點中的巨大作物、木樁、大石塊、隕石。 |
| piecesOfHay | NetInt | 筒倉中儲存的稻草數量。 |
| shippingBin | NetCollection of Item | 出貨箱裡的物品。 |