Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
OS¶
继承： Object
提供对常见操作系统功能的访问。
描述¶
这个类封装了与主机操作系统通信的最常见功能，例如视频驱动、延时、环境变量、二进制文件的执行、命令行等。
注意：在 Godot 4 中，窗口管理相关的 OS 函数已移动至 DisplayServer 单例。
教程¶
属性¶
|
||
|
||
|
方法¶
枚举¶
enum RenderingDriver:
RenderingDriver RENDERING_DRIVER_VULKAN = 0
Vulkan 渲染驱动。需要支持 Vulkan 1.0，而 Vulkan 1.1 和 1.2 的功能则会在支持时自动使用。
RenderingDriver RENDERING_DRIVER_OPENGL3 = 1
OpenGL 3 渲染驱动。在桌面平台上使用 OpenGL 3.3 核心配置，在移动设备上使用 OpenGL ES 3.0，在 Web 上使用 WebGL 2.0。
enum SystemDir:
SystemDir SYSTEM_DIR_DESKTOP = 0
桌面目录路径。
SystemDir SYSTEM_DIR_DCIM = 1
DCIM（数码相机图像）目录路径。
SystemDir SYSTEM_DIR_DOCUMENTS = 2
文档目录路径。
SystemDir SYSTEM_DIR_DOWNLOADS = 3
下载目录路径。
SystemDir SYSTEM_DIR_MOVIES = 4
影片目录路径。
SystemDir SYSTEM_DIR_MUSIC = 5
音乐目录路径。
SystemDir SYSTEM_DIR_PICTURES = 6
图片目录路径。
SystemDir SYSTEM_DIR_RINGTONES = 7
铃声目录路径。
属性说明¶
bool delta_smoothing = true
如果为 true，则引擎会在每帧之间过滤测量得到的时间增量，并尝试补偿随机变化。仅在启用垂直同步的系统上有效。
bool low_processor_usage_mode = false
如果为 true，则引擎会通过只在需要时刷新屏幕来优化处理器的使用。可以改善移动设备上的电池消耗。
int low_processor_usage_mode_sleep_usec = 6900
void set_low_processor_usage_mode_sleep_usec ( int value )
int get_low_processor_usage_mode_sleep_usec ( )
启用低处理器使用模式时，帧之间的休眠量（单位为微秒）。较高的值将导致较低的 CPU 使用率。
方法说明¶
void alert ( String text, String title="Alert!" )
使用主机操作系统显示一个模式化的对话框。执行将被阻塞，直到该对话框被关闭。
void close_midi_inputs ( )
关闭系统 MIDI 驱动程序。
注意：该方法只在 Linux、macOS 和 Windows 上实现。
void crash ( String message )
使引擎崩溃（如果是在 @tool 脚本中调用则为编辑器崩溃）。应该仅用于测试系统的崩溃处理器，其他情况下都不应使用。普通的错误汇报请使用 @GDScript.assert、@GlobalScope.push_error、alert（按推荐顺序排列）。另见 kill。
int create_instance ( PackedStringArray arguments )
创建一个独立运行的 Godot 新实例。arguments 按给定顺序使用，并以空格分隔。
如果进程创建成功，则该方法将返回新的进程 ID，可以使用它来监视该进程（并可能使用 kill 终止它）。如果进程创建失败，则该方法将返回 -1。
注意：该方法在 Android、iOS、Linux、macOS 和 Windows 上实现。
int create_process ( String path, PackedStringArray arguments, bool open_console=false )
创建一个独立于 Godot 运行的新进程。如果 Godot 终止，它也不会终止。path 中指定的路径必须存在，并且是可执行文件或 macOS .app 包。将使用平台路径解析。arguments 按给定顺序使用，并以空格分隔。
在 Windows 上，如果 open_console 为 true，并且该进程是一个控制台应用程序，则一个新的终端窗口将被打开。这在其他平台上将被忽略。
如果进程创建成功，则该方法将返回新的进程 ID，可以使用它来监视进程（并可能使用 kill 终止它）。如果进程创建失败，则该方法将返回 -1。
例如，运行项目的另一个实例：
var pid = OS.create_process(OS.get_executable_path(), [])
var pid = OS.CreateProcess(OS.GetExecutablePath(), new string[] {});
如果希望运行一个外部命令并检索结果，请参阅 execute。
注意：该方法在 Android、iOS、Linux、macOS 和 Windows 上实现。
注意：在 macOS 上，沙盒应用程序被限制为只能运行嵌入式辅助可执行文件，在导出或系统 .app 包期间指定，系统 .app 包将忽略参数。
void delay_msec ( int msec ) const
将当前线程的执行延迟 msec 毫秒。msec 必须大于或等于 0。否则，delay_msec 将不执行任何操作并打印一条错误消息。
注意：delay_msec 是一种阻塞延迟代码执行的方式。要以非阻塞的方式延迟代码执行，请参阅 SceneTree.create_timer。使用 SceneTree.create_timer 等待将会延迟那些放置在 await 下方的代码的执行，而不会影响该项目（或编辑器，对于 EditorPlugin 和 EditorScript）的其余部分。
注意：当在主线程上调用 delay_msec 时，它将冻结项目并阻止它重新绘制和注册输入，直到延迟结束。当使用 delay_msec 作为 EditorPlugin 或 EditorScript 的一部分时，它会冻结编辑器但不会冻结当前正在运行的项目（因为项目是一个独立的子进程）。
void delay_usec ( int usec ) const
将当前线程的执行延迟 usec 微秒。usec 必须大于或等于 0。否则，delay_usec 将不执行任何操作并打印一条错误消息。
注意：delay_usec 是一种阻塞延迟代码执行的方式。要以非阻塞的方式延迟代码执行，请参阅 SceneTree.create_timer。使用 SceneTree.create_timer 等待将会延迟那些放置在 await 下方的代码的执行，而不会影响该项目（或编辑器，对于 EditorPlugin 和 EditorScript）的其余部分。
注意：当在主线程上调用 delay_usec 时，它将冻结项目并阻止它重新绘制和注册输入，直到延迟结束。当使用 delay_usec 作为 EditorPlugin 或 EditorScript 的一部分时，它会冻结编辑器但不会冻结当前正在运行的项目（因为项目是一个独立的子进程）。
int execute ( String path, PackedStringArray arguments, Array output=[], bool read_stderr=false, bool open_console=false )
执行一条命令。path 中指定的文件必须存在且可执行。将使用平台路径解析。arguments 按给定顺序使用，以空格分隔，会使用引号包裹。如果提供了 output Array，则进程的完整 shell 输出，将作为单个 String 元素追加到 output 中。如果 read_stderr 为 true，则标准错误流的输出也将被包含在内。
在 Windows 上，如果 open_console 为 true 并且进程是控制台应用程序，则将打开一个新的终端窗口。该参数在其他平台上被忽略。
如果命令执行成功，该方法将返回命令的退出代码，如果失败则返回 -1。
注意：Godot 线程将暂停执行，直到执行的命令终止。使用 Thread 创建一个不会暂停 Godot 线程的独立线程，或者使用 create_process 创建一个完全独立的进程。
例如，要检索工作目录内容的列表：
var output = []
var exit_code = OS.execute("ls", ["-l", "/tmp"], output)
var output = new Godot.Collections.Array();
int exitCode = OS.Execute("ls", new string[] {"-l", "/tmp"}, output);
如果希望访问内置的 shell 或执行复合命令，则可以调用特定于平台的 shell。例如：
var output = []
OS.execute("CMD.exe", ["/C", "cd %TEMP% && dir"], output)
var output = new Godot.Collections.Array();
OS.Execute("CMD.exe", new string[] {"/C", "cd %TEMP% && dir"}, output);
注意：该方法在 Android、iOS、Linux、macOS 和 Windows 上实现。
注意：要执行 Windows 命令解释器的内置命令，在 path 中指定 cmd.exe，将 /c 作为第一个参数，并将所需的命令作为第二个参数。
注意：要执行 PowerShell 的内置命令，在 path 中指定 powershell.exe，将 -Command 作为第一个参数，然后将所需的命令作为第二个参数。
注意：要执行 Unix shell 内置命令，请在 path 中指定 shell 可执行文件名称，将 -c 作为第一个参数，并将所需的命令作为第二个参数。
注意：在 macOS 上，沙盒应用程序仅限于运行在导出期间指定的嵌入的辅助可执行文件。
Key find_keycode_from_string ( String string ) const
返回给定字符串（例如“Escape”）的键码。
String get_cache_dir ( ) const
根据操作系统的标准返回全局缓存数据目录。在 Linux/BSD 平台上，可以通过在启动项目之前设置 XDG_CACHE_HOME 环境变量来覆盖该路径。有关详细信息，请参阅文档中的《Godot 项目中的文件路径》。另请参阅 get_config_dir 和 get_data_dir。
不要与 get_user_data_dir 混淆，后者返回项目特定的用户数据路径。
PackedStringArray get_cmdline_args ( )
返回传递给引擎的命令行参数。
命令行参数可以写成任何形式，包括 --key value 和 --key=value 两种形式，这样它们就可以被正确解析，只要自定义命令行参数不与引擎参数冲突。
还可以使用 get_environment 方法合并环境变量。
可以设置 ProjectSettings.editor/run/main_run_args 来定义编辑器在运行项目时传递的命令行参数。
下面是一个关于如何使用参数的 --key=value 形式，将命令行参数解析为一个字典的最小示例：
var arguments = {}
for argument in OS.get_cmdline_args():
if argument.find("=") > -1:
var key_value = argument.split("=")
arguments[key_value[0].lstrip("--")] = key_value[1]
else:
# 没有参数的选项将出现在字典中，
# 其值被设置为空字符串。
arguments[argument.lstrip("--")] = ""
var arguments = new Godot.Collections.Dictionary();
foreach (var argument in OS.GetCmdlineArgs())
{
if (argument.Find("=") > -1)
{
string[] keyValue = argument.Split("=");
arguments[keyValue[0].LStrip("--")] = keyValue[1];
}
else
{
// 没有参数的选项将出现在字典中，
// 其值被设置为空字符串。
arguments[keyValue[0].LStrip("--")] = "";
}
}
注意：不建议直接传递自定义用户参数，因为引擎可能会丢弃或修改它们。相反，最好的方法是使用标准的 UNIX 双破折号（--），然后传递自定义参数，引擎本身将忽略这些参数。这些可以通过 get_cmdline_user_args 读取。
PackedStringArray get_cmdline_user_args ( )
类似于 get_cmdline_args，但它返回用户参数（在双破折号 -- 或双加号 ++ 参数之后传递的任何参数）。这些都是 Godot 为用户留下的，不做任何改动。++ 可用于 -- 被其他程序拦截的情况（如 startx）。
例如，在下面的命令行中，--fullscreen 不会在 get_cmdline_user_args 中返回，--level 1 只会在 get_cmdline_user_args 中返回：
godot --fullscreen -- --level 1
# 或：
godot --fullscreen ++ --level 1
String get_config_dir ( ) const
根据操作系统的标准，返回全局用户配置目录。在 Linux/BSD 平台上，可以通过在启动项目之前设置 XDG_CONFIG_HOME 环境变量来覆盖该路径。有关详细信息，请参阅文档中的《Godot 项目中的文件路径》。另请参阅 get_cache_dir 和 get_data_dir。
不要与 get_user_data_dir 混淆，后者返回项目专用的用户数据路径。
PackedStringArray get_connected_midi_inputs ( )
返回 MIDI 设备名称数组。
如果系统 MIDI 驱动程序之前没有使用 open_midi_inputs 进行初始化，则返回的数组将为空。
注意：该方法在 Linux、macOS 和 Windows 上实现。
String get_data_dir ( ) const
根据操作系统的标准返回全局用户数据目录。在 Linux/BSD 平台上，可以通过在启动项目之前设置 XDG_DATA_HOME 环境变量来覆盖该路径。有关详细信息，请参阅文档中的《Godot 项目中的文件路径》。另请参阅 get_cache_dir 和 get_config_dir。
不要与 get_user_data_dir 混淆，后者返回项目专用的用户数据路径。
String get_distribution_name ( ) const
返回 Linux 和 BSD 平台的发行版名称（例如 Ubuntu、Manjaro、OpenBSD 等）。
对于原生 Android 系统，返回与 get_name 相同的值，但对于 LineageOS 等流行的 Android 派生系统，尝试返回自定义 ROM 名称。
对于其他平台，返回与 get_name 相同的值。
注意：Web 平台上不支持这个方法。返回的是空字符串。
String get_environment ( String variable ) const
返回环境变量的值。如果环境变量不存在，则返回一个空字符串。
注意：请仔细检查 variable 的大小写。环境变量名称在除 Windows 之外的所有平台上都区分大小写。
String get_executable_path ( ) const
返回当前引擎可执行文件的路径。
注意：在 macOS 上，请始终使用 create_instance，不要依赖可执行文件的路径。
PackedStringArray get_granted_permissions ( ) const
在 Android 设备上：通过该功能，你可以获取已被授予的危险权限列表。
在 macOS 上（仅限沙盒应用程序）：该函数返回应用程序可访问的用户选择的文件夹列表。使用原生文件对话框请求文件夹访问权限。
String get_keycode_string ( Key code ) const
返回给定键码的字符串形式（例如，返回值："Escape"、"Shift+Escape"）。
另见 InputEventKey.keycode 和 InputEventKey.get_keycode_with_modifiers。
String get_locale ( ) const
将主机操作系统区域设置为 language_Script_COUNTRY_VARIANT@extra 形式的字符串。如果你只想要语言代码而不是操作系统中完全指定的语言环境，可以使用 get_locale_language。
language - 2 个或 3 个字母的语言代码，小写。
Script - 可选，4 个字母的文字代码，首字母大写。
COUNTRY - 可选，2 个或 3 个字母的国家地区代码，大写。
VARIANT - 可选，语言变体，地区和排序顺序。变体可以有任意数量的带下划线的关键字。
extra - 可选，分号分隔的附加关键字列表。货币、日历、排序顺序和编号系统信息。
String get_locale_language ( ) const
将主机操作系统区域设置的 2 或 3 个字母的语言代码作为字符串返回，该字符串应在所有平台上保持一致。这相当于提取 get_locale 字符串的 language 部分。
当你不需要有关国家/地区代码或变体的附加信息时，这可用于将完全指定的区域设置字符串缩小为“通用”语言代码。例如，对于使用 fr_CA 语言环境的加拿大法语用户，这将返回 fr。
int get_main_thread_id ( ) const
返回主线程的 ID。请参阅 get_thread_caller_id。
注意：线程 ID 不是确定的，也许会在应用程序重新启动时被重复使用。
Dictionary get_memory_info ( ) const
返回带有以下键的 Dictionary：
"physical" - 可用物理内存的总大小，单位为字节，未知时为 -1。这个值可能比实际的物理内存略小，因为计算时不含内核以及各种设备所保留的内存。
"free" - 在不访问磁盘、不进行其他高成本操作的前提下，能够立即分配的物理内存大小，单位为字节，未知时为 -1。进程也许能够分配更多的物理内存，但是这种分配会需要将不活跃的内存页移动至磁盘，可能花费较长时间。
"available" - 在不扩展交换文件的前提下，能够分配的内存大小，单位为字节，未知时为 -1。包括物理内存和交换分区大小。
"stack" - 当前线程的栈大小，单位为字节，未知时为 -1。
String get_model_name ( ) const
返回当前设备的模型名称。
注意：此方法仅在Android和iOS上实现。在不支持的平台上返回 "GenericDevice"。
String get_name ( ) const
返回主机操作系统的名称。
在 Windows 上为 "Windows"。
在 macOS 上为 "macOS"。
在基于 Linux 的操作系统上为 "Linux"。
在基于 BSD 的操作系统上为 "FreeBSD"、"NetBSD"、"OpenBSD", 会使用 "BSD" 作为回退方案。
在 Android 上为 "Android"。
在 iOS 上为 "iOS"。
在 Web 上为 "Web"。
注意：自定义构建的引擎可能支持其他平台，例如游戏主机，可能返回其他值。
match OS.get_name():
"Windows":
print("Windows")
"macOS":
print("macOS")
"Linux", "FreeBSD", "NetBSD", "OpenBSD", "BSD":
print("Linux/BSD")
"Android":
print("Android")
"iOS":
print("iOS")
"Web":
print("Web")
switch (OS.GetName())
{
case "Windows":
GD.Print("Windows");
break;
case "macOS":
GD.Print("macOS");
break;
case "Linux":
case "FreeBSD":
case "NetBSD":
case "OpenBSD":
case "BSD":
GD.Print("Linux/BSD");
break;
case "Android":
GD.Print("Android");
break;
case "iOS":
GD.Print("iOS");
break;
case "Web":
GD.Print("Web");
break;
}
int get_process_id ( ) const
返回项目的进程 ID。
注意：这个方法在 Android、iOS、Linux、macOS 和 Windows 上实现。
int get_processor_count ( ) const
返回主机的逻辑 CPU 核心数。对于启用了超线程的 CPU，这个数会比物理 CPU 核心数大。
String get_processor_name ( ) const
返回主机 CPU 型号的名称（例如 "Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz"）。
注意：该方法仅在 Windows、macOS、Linux 和 iOS 上实现。在 Android 和 Web 上，get_processor_name 返回空字符串。
PackedStringArray get_restart_on_exit_arguments ( ) const
返回当项目使用 set_restart_on_exit 自动重新启动时，将使用的命令行参数列表。另请参阅 is_restart_on_exit_set。
int get_static_memory_peak_usage ( ) const
返回使用的静态内存的最大数量（仅在调试时有效）。
int get_static_memory_usage ( ) const
返回程序所使用的静态内存量，以字节为单位（仅在调试时有效）。
String get_system_dir ( SystemDir dir, bool shared_storage=true ) const
返回不同平台上常用文件夹的实际路径。可用的位置在 SystemDir 中指定。
注意：这个方法在 Android、Linux、macOS 和 Windows 上实现。
注意：共享存储在 Android 上实现，并允许区分应用程序特定目录和共享目录。共享目录在 Android 上有额外的限制。
String get_system_font_path ( String font_name, int weight=400, int stretch=100, bool italic=false ) const
返回名称为 font_name 并且其他风格也相符的系统字体文件路径。如果没有相匹配的字体，则返回空字符串。
下列别名可用于请求默认字体：无衬线“sans-serif”、有衬线“serif”、等宽“monospace”、手写体“cursive”、花体“fantasy”。
注意：如果没有请求的风格，则可能返回不同风格的字体。
注意：该方法在 Android、iOS、Linux、macOS、Windows 上实现。
PackedStringArray get_system_font_path_for_text (