Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

OS

继承: Object

提供对常见操作系统功能的访问。

描述

这个类封装了与主机操作系统通信的最常见功能,例如视频驱动、延时、环境变量、二进制文件的执行、命令行等。

注意:在 Godot 4 中,窗口管理相关的 OS 函数已移动至 DisplayServer 单例。

教程

属性

bool

delta_smoothing

true

bool

low_processor_usage_mode

false

int

low_processor_usage_mode_sleep_usec

6900

方法

void

alert ( String text, String title="Alert!" )

void

close_midi_inputs ( )

void

crash ( String message )

int

create_instance ( PackedStringArray arguments )

int

create_process ( String path, PackedStringArray arguments, bool open_console=false )

void

delay_msec ( int msec ) const

void

delay_usec ( int usec ) const

int

execute ( String path, PackedStringArray arguments, Array output=[], bool read_stderr=false, bool open_console=false )

Key

find_keycode_from_string ( String string ) const

String

get_cache_dir ( ) const

PackedStringArray

get_cmdline_args ( )

PackedStringArray

get_cmdline_user_args ( )

String

get_config_dir ( ) const

PackedStringArray

get_connected_midi_inputs ( )

String

get_data_dir ( ) const

String

get_distribution_name ( ) const

String

get_environment ( String variable ) const

String

get_executable_path ( ) const

PackedStringArray

get_granted_permissions ( ) const

String

get_keycode_string ( Key code ) const

String

get_locale ( ) const

String

get_locale_language ( ) const

int

get_main_thread_id ( ) const

Dictionary

get_memory_info ( ) const

String

get_model_name ( ) const

String

get_name ( ) const

int

get_process_id ( ) const

int

get_processor_count ( ) const

String

get_processor_name ( ) const

PackedStringArray

get_restart_on_exit_arguments ( ) const

int

get_static_memory_peak_usage ( ) const

int

get_static_memory_usage ( ) const

String

get_system_dir ( SystemDir dir, bool shared_storage=true ) const

String

get_system_font_path ( String font_name, int weight=400, int stretch=100, bool italic=false ) const

PackedStringArray

get_system_font_path_for_text ( String font_name, String text, String locale="", String script="", int weight=400, int stretch=100, bool italic=false ) const

PackedStringArray

get_system_fonts ( ) const

int

get_thread_caller_id ( ) const

String

get_unique_id ( ) const

String

get_user_data_dir ( ) const

String

get_version ( ) const

PackedStringArray

get_video_adapter_driver_info ( ) const

bool

has_environment ( String variable ) const

bool

has_feature ( String tag_name ) const

bool

is_debug_build ( ) const

bool

is_keycode_unicode ( int code ) const

bool

is_process_running ( int pid ) const

bool

is_restart_on_exit_set ( ) const

bool

is_sandboxed ( ) const

bool

is_stdout_verbose ( ) const

bool

is_userfs_persistent ( ) const

Error

kill ( int pid )

Error

move_to_trash ( String path ) const

void

open_midi_inputs ( )

String

read_string_from_stdin ( )

bool

request_permission ( String name )

bool

request_permissions ( )

void

revoke_granted_permissions ( )

void

set_environment ( String variable, String value ) const

void

set_restart_on_exit ( bool restart, PackedStringArray arguments=PackedStringArray() )

Error

set_thread_name ( String name )

void

set_use_file_access_save_and_swap ( bool enabled )

Error

shell_open ( String uri )

Error

shell_show_in_file_manager ( String file_or_dir_path, bool open_folder=true )

void

unset_environment ( String variable ) const


枚举

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

  • void set_delta_smoothing ( bool value )

  • bool is_delta_smoothing_enabled ( )

如果为 true,则引擎会在每帧之间过滤测量得到的时间增量,并尝试补偿随机变化。仅在启用垂直同步的系统上有效。


bool low_processor_usage_mode = false

  • void set_low_processor_usage_mode ( bool value )

  • bool is_in_low_processor_usage_mode ( )

如果为 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_erroralert(按推荐顺序排列)。另见 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_consoletrue,并且该进程是一个控制台应用程序,则一个新的终端窗口将被打开。这在其他平台上将被忽略。

如果进程创建成功,则该方法将返回新的进程 ID,可以使用它来监视进程(并可能使用 kill 终止它)。如果进程创建失败,则该方法将返回 -1

例如,运行项目的另一个实例:

var pid = OS.create_process(OS.get_executable_path(), [])

如果希望运行一个外部命令并检索结果,请参阅 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 下方的代码的执行,而不会影响该项目(或编辑器,对于 EditorPluginEditorScript)的其余部分。

注意:当在主线程上调用 delay_msec 时,它将冻结项目并阻止它重新绘制和注册输入,直到延迟结束。当使用 delay_msec 作为 EditorPluginEditorScript 的一部分时,它会冻结编辑器但不会冻结当前正在运行的项目(因为项目是一个独立的子进程)。


void delay_usec ( int usec ) const

将当前线程的执行延迟 usec 微秒。usec 必须大于或等于 0。否则,delay_usec 将不执行任何操作并打印一条错误消息。

注意:delay_usec 是一种阻塞延迟代码执行的方式。要以非阻塞的方式延迟代码执行,请参阅 SceneTree.create_timer。使用 SceneTree.create_timer 等待将会延迟那些放置在 await 下方的代码的执行,而不会影响该项目(或编辑器,对于 EditorPluginEditorScript)的其余部分。

注意:当在主线程上调用 delay_usec 时,它将冻结项目并阻止它重新绘制和注册输入,直到延迟结束。当使用 delay_usec 作为 EditorPluginEditorScript 的一部分时,它会冻结编辑器但不会冻结当前正在运行的项目(因为项目是一个独立的子进程)。


int execute ( String path, PackedStringArray arguments, Array output=[], bool read_stderr=false, bool open_console=false )

执行一条命令。path 中指定的文件必须存在且可执行。将使用平台路径解析。arguments 按给定顺序使用,以空格分隔,会使用引号包裹。如果提供了 output Array,则进程的完整 shell 输出,将作为单个 String 元素追加到 output 中。如果 read_stderrtrue,则标准错误流的输出也将被包含在内。

在 Windows 上,如果 open_consoletrue 并且进程是控制台应用程序,则将打开一个新的终端窗口。该参数在其他平台上被忽略。

如果命令执行成功,该方法将返回命令的退出代码,如果失败则返回 -1

注意:Godot 线程将暂停执行,直到执行的命令终止。使用 Thread 创建一个不会暂停 Godot 线程的独立线程,或者使用 create_process 创建一个完全独立的进程。

例如,要检索工作目录内容的列表:

var output = []
var exit_code = OS.execute("ls", ["-l", "/tmp"], output)

如果希望访问内置的 shell 或执行复合命令,则可以调用特定于平台的 shell。例如:

var output = []
OS.execute("CMD.exe", ["/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_dirget_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("--")] = ""

注意:不建议直接传递自定义用户参数,因为引擎可能会丢弃或修改它们。相反,最好的方法是使用标准的 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_dirget_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_dirget_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.keycodeInputEventKey.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")

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 ( String font_name, String text, String locale="", String script="", 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_fonts ( ) const

返回可用的字体家族名称列表。

注意:该方法在 Android、iOS、Linux、macOS、Windows 上实现。


int get_thread_caller_id ( ) const

返回当前线程的 ID。这可用于日志,以简化多线程应用程序的调试。

注意:线程 ID 不是确定的,也许会在应用程序重新启动时被重复使用。


String get_unique_id ( ) const

返回特定于该设备的一个字符串。

注意:如果用户重新安装/升级他们的操作系统或更改他们的硬件,该字符串可能会更改,恕不另行通知。这意味着它通常不应用于加密持久数据,因为在意外的 ID 更改会使之前保存的数据将变得不可访问。返回的字符串也可能会被外部程序伪造,因此出于安全目的,不要依赖 get_unique_id 返回的字符串。

注意:在 Web 上返回一个空字符串,因为该方法尚未在该平台上实现。


String get_user_data_dir ( ) const

返回用于写入用户数据的绝对目录路径(user://)。

在 Windows 上,这是 %AppData%\Godot\app_userdata\[project_name];如果已设置 use_custom_user_dir,则为 %AppData%\[custom_name]%AppData% 扩展为 %UserProfile%\AppData\Roaming

在 macOS 上,这是 ~/Library/Application Support/Godot/app_userdata/[project_name];如果已设置 use_custom_user_dir,则为 ~/Library/Application Support/[custom_name]

在 Linux 和 BSD 上,这是 ~/.local/share/godot/app_userdata/[project_name];如果已设置 use_custom_user_dir,则为 ~/.local/share/[custom_name]

在 Android 和 iOS 上,这是内部存储或外部存储中的沙盒目录,具体取决于用户的配置。

在 Web 上,这是由浏览器管理的虚拟目录。

如果项目名称为空,则 [project_name] 将回退为 [unnamed project]

请勿与 get_data_dir 混淆,后者返回的是全局(非项目特定的)用户主目录。


String get_version ( ) const

返回操作系统的确切生产和构建版本。这与营销中使用的品牌版本不同。这有助于区分操作系统的不同版本,包括次要版本、内部版本和自定义版本。

对于 Windows,返回主要和次要版本,以及构建号。例如,对于 Windows 10 版本,返回的字符串可能看起来像 10.0.9926,对于 Windows 7 SP1 版本,它可能看起来像 6.1.7601

对于滚动发行版,例如 Arch Linux,会返回一个空字符串。

对于 macOS 和 iOS,会返回主要和次要版本,以及补丁号。

对于 Android,会返回 SDK 版本和增量构建号。如果是自定义的 ROM,将会尝试返回其版本。

注意:该方法在 web 平台上不被支持。它将返回一个空字符串。


PackedStringArray get_video_adapter_driver_info ( ) const

返回用户当前激活的显卡的视频适配器驱动程序名称和版本。另见 RenderingServer.get_video_adapter_api_version

第一个元素保存驱动程序的名称,如 nvidiaamdgpu 等。

第二个元素保存驱动程序的版本。例如 Linux/BSD 平台上的 nvidia 驱动程序,其版本格式为 510.85.02。对于 Windows,其驱动程序的格式是 31.0.15.1659

注意:该方法仅在 Linux/BSD 和 Windows 平台上不以无头模式运行时才受支持。在其他平台上返回一个空数组。


bool has_environment ( String variable ) const

如果名称为 variable 的环境变量存在,则返回 true

注意:请仔细检查 variable 的大小写。环境变量名称在除 Windows 之外的所有平台上都区分大小写。


bool has_feature ( String tag_name ) const

如果当前运行的实例支持给定功能标签的功能,则返回 true,具体取决于平台、构建等。可用于检查当前是否正在运行调试构建,是否在某个平台或架构上,等等。详情见《功能标签》文档。

注意:标签名称区分大小写。

注意:在 Web 平台上,会定义 web_androidweb_iosweb_linuxbsdweb_macosweb_windows 的其中之一,表示宿主平台。

注意:在 iOS 模拟器中,还会定义 simulator 标签。


bool is_debug_build ( ) const

如果用于运行项目的 Godot 二进制文件是调试导出模板,或是在编辑器中运行时,则返回 true

如果用于运行项目的 Godot 二进制文件是发布导出模板,则返回 false

要检查用于运行项目的 Godot 二进制文件是否是导出模板(调试或发布),请改用 OS.has_feature("template")


bool is_keycode_unicode ( int code ) const

如果输入键码对应一个 Unicode 字符,则返回 true


bool is_process_running ( int pid ) const

如果该子进程 ID(pid)仍在运行,则返回 true;如果它已终止,则返回 false

必须是从 create_process 生成的有效 ID。

注意:该方法在 Android、iOS、Linux、macOS 和 Windows 上实现。


bool is_restart_on_exit_set ( ) const

如果项目因任何原因退出时将自动重新启动,则返回 true,否则返回 false。另请参阅 set_restart_on_exitget_restart_on_exit_arguments


bool is_sandboxed ( ) const

如果应用程序在沙箱中运行,则返回 true

注意:该方法在 macOS 和 Linux 上实现。


bool is_stdout_verbose ( ) const

如果引擎是使用 --verbose-v 命令行参数执行的,或者如果 ProjectSettings.debug/settings/stdout/verbose_stdouttrue,则返回 true。另请参阅 @GlobalScope.print_verbose


bool is_userfs_persistent ( ) const

如果为 true,则 user:// 文件系统是持久的,所以在玩家退出并再次开始游戏后,它的状态是相同的。与 Web 平台相关时,该持久性可能不可用。


Error kill ( int pid )

杀死(终止)由给定进程 ID(pid)标识的进程,例如由 execute 在非阻塞模式下返回的那个进程 ID。另请参阅 crash

注意:该方法也可用于杀死不是由游戏产生的进程。

注意:该方法在 Android、iOS、Linux、macOS 和 Windows 上实现。


Error move_to_trash ( String path ) const

将文件或目录移动到系统的回收站。另见 DirAccess.remove

该方法仅支持全局路径,所以可能需要使用 ProjectSettings.globalize_path。请勿将其用于 res:// 中的文件,因为它在导出后的项目中是无法正常工作的。

注意:如果用户在系统上禁用了回收站,则该文件将被永久删除。

var file_to_remove = "user://slot1.save"
OS.move_to_trash(ProjectSettings.globalize_path(file_to_remove))

void open_midi_inputs ( )

初始化系统 MIDI 驱动的单例。

注意:该方法在 Linux、macOS、Windows 上实现。


String read_string_from_stdin ( )

从标准输入(通常是终端)读取一个用户输入字符串。这个操作是阻塞的 ,如果在主线程上调用 read_string_from_stdin,就会导致窗口冻结。调用 read_string_from_stdin 的线程将被阻塞,直到程序在标准输入中接收到一个断行(通常由用户按下 Enter)。

注意:该方法在 Linux、macOS 和 Windows 上实现。


bool request_permission ( String name )

目前,这个函数只被 AudioDriverOpenSL 用来请求 Android 上 RECORD_AUDIO 的权限。


bool request_permissions ( )

你可以通过这个函数申请危险的权限,因为在 Android 应用程序中,正常的权限会在安装时自动授予。

注意:该方法仅在 Android 上实现。


void revoke_granted_permissions ( )

在 macOS(仅限沙盒应用程序)上,该功能会清除应用程序可访问的用户选择的文件夹列表。


void set_environment ( String variable, String value ) const

将环境变量 variable 的值设置为 value。运行 set_environment 后,会为 Godot 进程和任何用 execute 执行的进程设置该环境变量。该环境变量不会持续存在于 Godot 进程终止后运行的进程中。

注意:环境变量的名称在除 Windows 外的所有平台上都是区分大小写的。名称 variable 不能为空,也不能包含 = 字符。在 Windows 上,在环境块中注册的 variablevalue= 以及 null 终止符的总长度有 32767 个字符的限制。


void set_restart_on_exit ( bool restart, PackedStringArray arguments=PackedStringArray() )

如果 restarttrue,则项目在使用 SceneTree.quitNode.NOTIFICATION_WM_CLOSE_REQUEST 退出时,会自动重新启动。可以提供命令行 arguments。要使用最初用于运行项目的命令行参数重新启动项目,请将 get_cmdline_args 作为 arguments 的值传递。

set_restart_on_exit 可用于应用需要重新启动的设置更改。另见 is_restart_on_exit_setget_restart_on_exit_arguments

注意:该方法只在桌面平台上有效,并且只在项目不是从编辑器启动时有效。不会影响移动和 Web 平台,或者当项目从编辑器启动时。

注意:如果项目进程崩溃或被用户杀死(通过发送 SIGKILL 而不是通常的 SIGTERM),项目不会自动重新启动。


Error set_thread_name ( String name )

设置当前线程的名称。


void set_use_file_access_save_and_swap ( bool enabled )

如果 enabledtrue,则启用备份保存。


Error shell_open ( String uri )

请求操作系统使用最合适的程序打开资源。例如:

  • OS.shell_open("C:\\Users\name\Downloads") 在 Windows 上会用资源管理器打开用户的 Downloads 文件夹。

  • OS.shell_open("https://godotengine.org") 会使用默认网页浏览器打开 Godot 官方网站。

  • OS.shell_open("mailto:example@example.com") 会打开默认电子邮件客户端并将“收件人”字段设置为 example@example.com。其他支持自定义的字段见 RFC 2368 - [code]mailto[/code] URL 方案

可以使用 ProjectSettings.globalize_pathres://user:// 路径转换为本方法所使用的系统路径。

注意:请使用 String.uri_encode 对 URL 中的字符进行编码,得到的 URL 才能安全使用、可移植。尤其是在包含换行的情况下。否则项目导出至 Web 平台后 shell_open 可能无法正常工作。

注意:这个方法在 Android、iOS、HTML5、Linux、macOS、以及 Windows 上实现。


Error shell_show_in_file_manager ( String file_or_dir_path, bool open_folder=true )

请求操作系统打开文件管理器,然后导航至给定的文件或目录路径 file_or_dir_path 并选中目标文件或文件夹。

如果 file_or_dir_path 为有效的目录路径,并且 open_foldertrue,则该方法会打开文件管理器并进入目标文件夹,不会选中任何东西。

请使用 ProjectSettings.globalize_pathres://user:// 路径转换为能够用于这个方法的文件系统路径。

注意:目前该方法仅在 Windows 和 macOS 上实现。在其他平台上会回退至使用前缀 file://file_or_dir_path 目录路径调用 shell_open


void unset_environment ( String variable ) const

从当前环境中移除环境变量 variable(如果存在)。在运行 unset_environment 后,将为 Godot 进程和使用 execute 执行的任何进程移除环境变量。环境变量的移除并不会持续到 Godot 进程终止后运行的进程。

注意:环境变量名称在除 Windows 以外的所有平台上都区分大小写。variable 名称不能为空或包含 = 字符。