🔨 配置文件 API

這裡為你提供了處理 大量數據 時的多種可選方案

在插件工作過程中，難免會碰到需要處理配置和大量遊戲相關數據的場景。
腳本引擎為腳本插件提供了大量基礎設施，包括配置文件、數據庫、經濟系統等。
方便開發者專注於業務代碼實現，而非糾結於這些方面的技術細節。

🔨 配置文件 API

配置文件，一般用於將插件的某些可供用戶修改的設置項獨立成文件，以方便修改某些設置。
因此，配置文件的內容和格式一般需要有一定的可讀性。
腳本引擎提供 ConfigFile 配置文件接口來完成這個任務。
當然，你也可以手動讀寫文件來協助相關配置文件的操作。

說明：配置文件類型的選擇

配置文件格式的選擇，將影響你可以儲存的配置數據類型。

• JSON（JS Object Notation） 格式可以儲存大多數類型的數據，包括數組、對象等，表示的邏輯相對豐富
• Ini（Initialization File） 格式相對簡單直觀，他人修改起來非常輕鬆，不過儲存的數據類型受到一定限制

請按需做出選擇。

📰 JSON 格式配置文件

創建 / 打開一個 JSON 配置文件

[JavaScript] new JsonConfigFile(path[,default])
[Lua] JsonConfigFile(path[,default])

• 參數：
• path : String
  配置文件所在路徑，以BDS根目錄為基準
  如果配置文件路徑中有目錄尚不存在，腳本引擎會自動創建
• default : String
  （可選參數）配置文件的默認內容。
  如果初始化時目標文件不存在，引擎將新建一個配置文件並將此處的默認內容寫入文件中。
  如果不傳入此參數，新建時的配置文件將為空
• 返回值：打開 / 創建的配置文件對象
• 返回值類型：JsonConfigFile
• 如果創建 / 打開失敗，將拋出異常

我們建議你在 BDS根目录/plugins/插件名字/ 目錄下建立名為config.json的配置文件，以保持各插件的配置統一

對於一個 JSON 配置文件對象conf，你有這些讀寫接口可用

初始化配置項（方便函數）

conf.init(name,default)

• 參數：
• name : String
  配置項名字
• default : 任意类型
  配置項初始化時寫入的值
• 返回值：指定配置項的數據
• 返回值類型：任意类型，以具體儲存的數據類型為準

這裡提供了一種簡便的方法來初始化配置文件，避免了需要手寫默認配置文件內容的麻煩

如果init訪問的配置項不存在，那麼引擎將在配置文件中自動創建此項，並寫入給出的默認值
如果init訪問的配置項已經存在，引擎將讀取並返回配置文件中已有的值

寫入配置項

conf.set(name,data)

• 參數：

• name : String
  配置項名字

• data : 任意类型
  要寫入的配置數據。允許的數據類型有：
  Integer Float String Boolean Array Object
  其中，Array 和 Object 內部僅能嵌套上面這些元素

• 返回值：是否寫入成功

• 返回值類型：Boolean

讀取配置項

conf.get(name[,default])

• 參數：
• name : String
  配置項名字
• default : 任意类型
  （可選參數）當讀取失敗時返回的默認值
  默認為Null
• 返回值：指定配置項的數據
• 返回值類型：任意类型，以具體儲存的數據類型為準

刪除配置項

conf.delete(name)

• 參數：
• name : String
  配置項名字
• 返回值：是否刪除成功
• 返回值類型：Boolean

如果這個配置項你不需要了，為了避免在他人修改配置文件時引起迷惑，你可以選擇將它刪除

📄 Ini 格式配置文件

創建 / 打開一個 Ini 配置文件

[JavaScript] new IniConfigFile(path[,default])
[Lua] IniConfigFile(path[,default])

• 參數：
• path : String
  配置文件所在路徑，以BDS根目錄為基準
  如果配置文件路徑中有目錄尚不存在，腳本引擎會自動創建
• default : String
  （可選參數）配置文件的默認內容。
  如果初始化時目標文件不存在，引擎將新建一個配置文件並將此處的默認內容寫入文件中。
  如果不傳入此參數，新建時的配置文件將為空
• 返回值：打開 / 創建的配置文件對象
• 返回值類型：IniConfigFile
• 如果創建 / 打開失敗，將拋出異常

我們建議你在 BDS根目录/plugins/插件名字/ 目錄下建立名為config.ini的配置文件，以保持各插件的配置統一

對於一個 Ini 配置文件對象conf，你有這些讀寫接口可用

初始化配置項（方便函數）

conf.init(section,name,default)

• 參數：
• section : String
  配置項鍵名
• name : String
  配置項名字
• default : 任意类型
  配置項初始化時寫入的值。允許的數據類型有：
  Integer Float String Boolean
• 返回值：指定配置項的數據
• 返回值類型：任意类型，以具體儲存的數據類型為準

這裡提供了一種簡便的方法來初始化配置文件，避免了需要手寫默認配置文件內容的麻煩

如果init訪問的配置項不存在，那麼引擎將在配置文件中自動創建此項，並寫入給出的默認值
如果init訪問的配置項已經存在，引擎將讀取並返回配置文件中已有的值

寫入配置項

conf.set(section,name,data)

• 參數：

• section : String
  配置項鍵名

• name : String
  配置項名字

• data : 任意类型
  要寫入的配置數據。允許的數據類型有：
  Integer Float String Boolean

• 返回值：是否寫入成功

• 返回值類型：Boolean

如果配置項不存在，接口會自動創建

讀取配置項

讀取字符串 conf.getStr(section,name[,default])
讀取整數項 conf.getInt(section,name[,default])
讀取浮點數 conf.getFloat(section,name[,default])
讀取布爾值 conf.getBool(section,name[,default])

• 參數：
• section : String
  配置項鍵名
• name : String
  配置項名字
• default : String/ Integer/ Float/ Boolean
  （可選參數）當讀取失敗時返回的默認值
  默認為0
• 返回值：指定配置項的數據
• 返回值類型：String/ Integer/ Float/ Boolean

刪除配置項

conf.delete(section,name)

• 參數：
• section : String
  配置項鍵名
• name : String
  配置項名字
• 返回值：是否刪除成功
• 返回值類型：Boolean

如果這個配置項你不需要了，為了避免在他人修改配置文件時引起迷惑，你可以選擇將它刪除

💼 其他的通用接口函數

對於一個配置文件對象conf，你可以使用這些輔助用途的通用接口

重新加載文件中的配置項

conf.reload()

• 返回值：是否成功加載

為了性能考慮，配置文件接口對讀操作進行緩存，每次讀取操作都從直接內存中讀取，而寫入才會直接寫入磁盤文件。考慮到配置文件可能被用戶修改，當你確認用戶已經修改配置文件之後，需要使用此函數刷新配置文件的內存緩存數據。

關閉配置文件

conf.close()

• 返回值：是否成功關閉

配置文件關閉之後，請勿繼續使用！

獲取配置文件路徑

conf.getPath()

• 返回值：當前配置文件的文件路徑
• 返回值類型：String

讀取整個配置文件的內容

conf.read()

• 返回值：當前配置文件的所有內容
• 返回值類型：String

寫入整個配置文件的內容

conf.write(content)

• 參數：
• content : String
  寫入的內容
• 返回值：是否寫入成功
• 返回值類型：Boolean