diff --git a/docs/apis/ScriptAPI/Logger.md b/docs/apis/ScriptAPI/Logger.md index af58810..ce257e4 100644 --- a/docs/apis/ScriptAPI/Logger.md +++ b/docs/apis/ScriptAPI/Logger.md @@ -1,22 +1,24 @@ # LLSE - Script Assist Interface Documentation -> A large number of **helper functions** are provided here, including log functions, loader function interfaces, and more. +> A large number of **helper functions** are provided here, including log functions, loader function interfaces, and +> more. They make it easier and more natural for you to develop scripts and avoid a lot of unnecessary details. -## 📅 Generic logging API +## 📅 Generic logging API -In the past, it was a very troublesome thing to output logs in a certain format to a specified location. -Today, LLSE provides you with a convenient generic logging interface. +In the past, it was a very troublesome thing to output logs in a certain format to a specified location. +Today, LLSE provides you with a convenient generic logging interface. ### Concept: About log output levels In order to rank the priority and importance of logs, we introduce the concept of **log output level**. -The higher the log output level, the more detailed the content of the log, but the larger the amount of logs output at the same time. -See the table below for details: +The higher the log output level, the more detailed the content of the log, but the larger the amount of logs output at +the same time. +See the table below for details: | Log Output Level | Log Severity | Log Description | -| ---------------- | ------------ | ---------------------------------------- | +|------------------|--------------|------------------------------------------| | 0 | Slient | No log output. | | 1 | Fatal | Only critical error messages. | | 2 | Error | Only error and critical error messages. | @@ -24,70 +26,67 @@ See the table below for details: | 4 | Info | Output everythng except debug info. | | 5 | Debug | Output everything. | -With the **Log output level** setting, you can easily filter out some unnecessary information in the production environment. - -The default value of the log output level is `4`, that is, all kinds of logs other than debug information will be output. -With some APIs given below, you can adjust the log output level to your own desired value. - +With the **Log output level** setting, you can easily filter out some unnecessary information in the production +environment. +The default value of the log output level is `4`, that is, all kinds of logs other than debug information will be +output. +With some APIs given below, you can adjust the log output level to your own desired value. ### Set Output Configuration -Before using the general log interface, you need to modify some configuration settings of the log output according to your needs. +Before using the general log interface, you need to modify some configuration settings of the log output according to +your needs. You can freely choose to send the log to the console, file or even a player by modifying the settings. These settings can exist at the same time, for example, you can set to send to the console and file at the same time. -If you don't change any settings, by **default** the log will only be output to the console. +If you don't change any settings, by **default** the log will only be output to the console. #### Set whether the log is output to the console `logger.setConsole(isOpen[,logLevel])` - Parameter: - - isOpen : `Boolean` - Set whether the log is output to the console - The switch is on by default. - - logLevel : `Integer` - (optional parameter) the log output level of the console, the default is `4` -- Return value: none - - + - isOpen : `Boolean` + Set whether the log is output to the console + The switch is on by default. + - logLevel : `Integer` + (optional parameter) the log output level of the console, the default is `4` +- Return value: none #### Set whether the log is output to a file `logger.setFile(filepath[,logLevel])` - Parameter: - - filepath : `String` - Set the file path where logs are output. - If you pass in an empty string or `Null`, then output to a file is closed. - The switch is off by default. - - logLevel : `Integer` - (optional parameter) the minimum log output level of the file, the default is `4` -- Return value: none - -If you want to output to a file, we recommend that you output the log uniformly to `BDS_Root_Directory/logs/` folder for easy organization and inspection. - + - filepath : `String` + Set the file path where logs are output. + If you pass in an empty string or `Null`, then output to a file is closed. + The switch is off by default. + - logLevel : `Integer` + (optional parameter) the minimum log output level of the file, the default is `4` +- Return value: none +If you want to output to a file, we recommend that you output the log uniformly to `BDS_Root_Directory/logs/` folder for +easy organization and inspection. #### Set whether the log is output to a certain player `logger.setPlayer(player[,logLevel])` - Parameter: - - player : `Player` - Set the target player object for sending logging output. - If it returns `Null`, output to the player is closed. - The switch is off by default - - logLevel : `Integer` - (optional parameter) The player's minimum log output level, defaults to `4` -- Return value: none - -This is a function designed to facilitate in-game debugging. The log output to the player will be treated as a chat message and displayed on the target player's screen. - + - player : `Player` + Set the target player object for sending logging output. + If it returns `Null`, output to the player is closed. + The switch is off by default + - logLevel : `Integer` + (optional parameter) The player's minimum log output level, defaults to `4` +- Return value: none +This is a function designed to facilitate in-game debugging. The log output to the player will be treated as a chat +message and displayed on the target player's screen. - ### Output Log Function +### Output Log Function After the setup is complete, you can use the function here to output the log. @@ -99,32 +98,51 @@ After the setup is complete, you can use the function here to output the log. `logger.fatal(data1,data2,...)` -> Output critical error message - Parameter: - - Variable or data to be output - Can be of any type, and the number of parameters can be any number. -- Return value: none + - Variable or data to be output + Can be of any type, and the number of parameters can be any number. +- Return value: none -Among them, **ordinary text** will be output as it is when output, while other output interfaces will append the **current time and log type.** +Among them, **ordinary text** will be output as it is when output, while other output interfaces will append the * +*current time and log type.** For example: you call `logger.error("Fail to transport the player")` -The result of the log output is: +The result of the log output is: ```log [2021-05-21 19:41:03 Error] Fail to transport the player ``` - - ### Other Settings In addition, there are other settings to change the format of the output log +#### Set custom log message headers + +`logger.setTitle(title)` + +- Parameter: + - title : `String` + Set custom headers +- Return value: none + +"Header" is the text at the beginning of the log output entry, which is used to visually distinguish the output source +of the log. +By default, message headers are empty by default, i.e. output without headers. + +For example: set a custom header as `logger.setTitle("LeviLamina")` +Then the following log output will become like: + +```log +20:05:26 ERROR [LeviLamina] Fail to transport the player +``` + #### Unified modification log output level `logger.setLogLevel(level)` - Parameter: - - level : `Integer` - Log output level -- Return value: none + - level : `Integer` + Log output level +- Return value: none Unified reset of log output levels for various output directions diff --git a/docs/apis/ScriptAPI/Logger.zh.md b/docs/apis/ScriptAPI/Logger.zh.md index 6ce3cd6..0a25412 100644 --- a/docs/apis/ScriptAPI/Logger.zh.md +++ b/docs/apis/ScriptAPI/Logger.zh.md @@ -1,13 +1,13 @@ # 脚本引擎 - 脚本辅助接口文档 -> 这里提供了大量的 **辅助功能** ，包括日志功能、加载器功能接口等等。 +> 这里提供了大量的 **辅助功能** ，包括日志功能、加载器功能接口等等。 他们让你开发脚本变得更加容易而自然，避免了很多无谓的细节问题的纠缠。 ## 📅 通用日志 API 以往，按某种格式输出日志到指定位置是一件非常麻烦的事情。 -如今，脚本引擎为你提供了方便的通用日志接口。 +如今，脚本引擎为你提供了方便的通用日志接口。 ### 概念：关于日志输出等级 @@ -15,21 +15,19 @@ 日志输出等级越高，日志的内容越详细，但同时输出的日志量也越大 详见下表： -| 日志输出等级 | 对应等级名称 | 实际输出日志内容 | -| ------------ | ------------ | ------------------------------------------- | -| 0 | Slient | 不输出任何日志 | -| 1 | Fatal | 仅输出 严重错误信息 | -| 2 | Error | 输出 严重错误、错误信息 | -| 3 | Warn | 输出 严重错误、错误、警告信息 | -| 4 | Info | 输出 严重错误、错误、警告、提示信息 | -| 5 | Debug | 输出 严重错误、错误、警告、提示 和 调试信息 | +| 日志输出等级 | 对应等级名称 | 实际输出日志内容 | +|--------|--------|-------------------------| +| 0 | Slient | 不输出任何日志 | +| 1 | Fatal | 仅输出 严重错误信息 | +| 2 | Error | 输出 严重错误、错误信息 | +| 3 | Warn | 输出 严重错误、错误、警告信息 | +| 4 | Info | 输出 严重错误、错误、警告、提示信息 | +| 5 | Debug | 输出 严重错误、错误、警告、提示 和 调试信息 | 通过 **日志输出等级** 设置，你可以很方便地过滤掉某些在生产环境中没必要输出的信息。 日志输出等级的默认值为`4`，也就是说，除了调试信息以外其他种类的日志都将被输出。 -通过下面给出的一些 API ，你可以将日志输出等级调整为你自己想要的值。 - - +通过下面给出的一些 API ，你可以将日志输出等级调整为你自己想要的值。 ### 设置输出配置 @@ -44,50 +42,44 @@ `logger.setConsole(isOpen[,logLevel])` - 参数： - - isOpen : `Boolean` - 设置日志是否输出到控制台 - 开关默认是打开状态。 - - logLevel : `Integer` - （可选参数）控制台的日志输出等级，默认为`4` + - isOpen : `Boolean` + 设置日志是否输出到控制台 + 开关默认是打开状态。 + - logLevel : `Integer` + （可选参数）控制台的日志输出等级，默认为`4` - 返回值：无 - - #### 设置日志是否输出到文件 `logger.setFile(filepath[,logLevel])` - 参数： - - filepath : `String` - 设置日志输出到的文件路径 - 如果传入空字符串或者`Null`，则代表关闭到文件的输出。 - 开关默认是关闭状态 - - logLevel : `Integer` - （可选参数）文件的最小日志输出等级，默认为`4` + - filepath : `String` + 设置日志输出到的文件路径 + 如果传入空字符串或者`Null`，则代表关闭到文件的输出。 + 开关默认是关闭状态 + - logLevel : `Integer` + （可选参数）文件的最小日志输出等级，默认为`4` - 返回值：无 如果要输出到文件，我们提倡您将日志统一输出到`BDS根目录/logs/`文件夹下，以方便整理和检查。 - - #### 设置日志是否输出到某个玩家 `logger.setPlayer(player[,logLevel])` - 参数： - - player : `Player` - 设置日志输出到的目标玩家对象 - 如果传入`Null`，则代表关闭到玩家的输出。 - 开关默认是关闭状态 - - logLevel : `Integer` - （可选参数）玩家的最小日志输出等级，默认为`4` + - player : `Player` + 设置日志输出到的目标玩家对象 + 如果传入`Null`，则代表关闭到玩家的输出。 + 开关默认是关闭状态 + - logLevel : `Integer` + （可选参数）玩家的最小日志输出等级，默认为`4` - 返回值：无 这是为了方便游戏内调试而设计的功能，输出到玩家的日志会被当作聊天消息，显示在目标玩家的屏幕上 - - - ### 输出日志函数 +### 输出日志函数 在设置完毕之后，你就可以用这里的函数输出日志了 @@ -99,31 +91,48 @@ `logger.fatal(data1,data2,...)` -> 输出严重错误信息 - 参数： - - 待输出的变量或者数据 - 可以是任意类型，参数数量可以是任意个 + - 待输出的变量或者数据 + 可以是任意类型，参数数量可以是任意个 - 返回值：无 其中，**普通文本**在输出的时候会按照原样输出，而其他的各个输出接口都会在日志内容前面附加上**当前时间和日志类型** 例如：你调用`logger.error("Fail to transport the player")` -日志输出的结果是 +日志输出的结果是 ```log [2021-05-21 19:41:03 Error] Fail to transport the player ``` - - ### 其他的一些设置项 除此之外，还有其他的一些设置项，用来改变输出日志的格式 +#### 设置自定义日志消息标头 + +`logger.setTitle(title)` + +- 参数： + - title : `String` + 设置的自定义标头 +- 返回值：无 + +「标头」为日志输出条目开头的文字，用来直观地区分日志的输出源。 +默认情况下，消息标头默认为空，即输出时没有标头。 + +例如：设置自定义标头为`logger.setTitle("LeviLamina")` +则在接下来的日志输出将变为形如： + +```log +20:05:26 ERROR [LeviLamina] Fail to transport the player +``` + #### 统一修改日志输出等级 `logger.setLogLevel(level)` - 参数： - - level : `Integer` - 日志输出等级 + - level : `Integer` + 日志输出等级 - 返回值：无 统一重设各种输出方向的日志输出等级