Up to date

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

Rutas de archivo en proyectos de Godot

Esta página explica cómo funcionan las rutas de archivos dentro de los proyectos de Godot. Aprenderás cómo acceder a las rutas en tus proyectos utilizando las notaciones res:// y user://, y dónde Godot almacena los archivos del proyecto y del editor en tu sistema y en los sistemas de tus usuarios.

Separadores de rutas

Para facilitar el soporte de múltiples plataformas, Godot utiliza separadores de ruta en estilo UNIX (barra diagonal hacia adelante "/"). Estos funcionan en todas las plataformas, incluyendo Windows.

En lugar de escribir rutas como C:\Projects\Game, en Godot, usted deberia escribir C:/Projects/Game.

También se admiten los separadores de ruta en estilo Windows (barra invertida \) en algunos métodos relacionados con las rutas, pero deben duplicarse (\\), ya que la barra invertida \ se utiliza normalmente como un escape para caracteres con un significado especial.

Esto hace posible trabajar con rutas devueltas por otras aplicaciones de Windows. Aún así, recomendamos utilizar solo barras diagonales hacia adelante en tu propio código para garantizar que todo funcione según lo previsto.

Accediento a los archivos en la carpeta del proyecto (res://)

Godot considera que un proyecto existe en cualquier carpeta que contenga un archivo de texto llamado project.godot, incluso si el archivo está vacío. La carpeta que contiene este archivo es la carpeta raíz de tu proyecto.

Puedes acceder a cualquier archivo relativo a él escribiendo rutas que comiencen con res://, que representa los recursos. Por ejemplo, puedes acceder a un archivo de imagen character.png ubicado en la carpeta raíz del proyecto en el código con la siguiente ruta: res://character.png.

Accediendo a los datos persistentes del usuario (user://)

Para almacenar archivos de datos persistentes, como el guardado del jugador o la configuración, es recomendable utilizar user:// en lugar de res:// como prefijo de ruta. Esto se debe a que cuando el juego se está ejecutando, es probable que el sistema de archivos del proyecto sea de solo lectura.

El prefijo user:// apunta a un directorio diferente en el dispositivo del usuario. A diferencia de res://, el directorio al que apunta user:// se crea automáticamente y se garantiza que es escribible, incluso en un proyecto exportado.

La ubicación de la carpeta user:// depende de lo que esté configurado en la Configuración del Proyecto:

  • De forma predeterminada, la carpeta user:// se crea dentro de la ruta editor data path <doc_data_paths_editor_data_paths>`de datos del editor de Godot en la carpeta ``app_userdata/[nombre_del_proyecto]`. Esto se hace de manera predeterminada para que los prototipos y proyectos de prueba se mantengan autocontenidos dentro de la carpeta de datos de Godot.

  • Si la opción application/config/use_custom_user_dir está habilitada en la Configuración del Proyecto, la carpeta user:// se crea junto a la ruta de datos del editor de Godot, es decir, en la ubicación estándar para los datos de las aplicaciones.

    • De forma predeterminada, el nombre de la carpeta se deduce a partir del nombre del proyecto, pero se puede personalizar aún más con application/config/custom_user_dir_name. Esta ruta puede contener separadores de ruta, por lo que puedes utilizarla, por ejemplo, para agrupar proyectos de un estudio determinado con una estructura NombreDelEstudio/NombreDelJuego.

En plataformas de escritorio, las rutas de directorio reales para user:// son las siguientes:

Tipo

Localización

Predeterminado

Windows: %APPDATA%\Godot\app_userdata\[project_name]
macOS: ~/Library/Application Support/Godot/app_userdata/[project_name]
Linux: ~/.local/share/godot/app_userdata/[project_name]

Directorios personalizados

Windows: %APPDATA%\[project_name]
macOS: ~/Library/Application Support/[project_name]
Linux: ~/.local/share/[project_name]

Directorio y nombre personalizado

Windows: %APPDATA%\[nombre_de_directorio_personalizado]
macOS: ~/Library/Application Support/[nombre_de_directorio_personalizado]
Linux: ~/.local/share/[nombre_de_directorio_personalizado]

[project_name] se basa en el nombre de la aplicación definido en la Configuración del Proyecto, pero puedes reemplazarlo de forma individual por plataforma utilizando etiquetas de características.

En plataformas móviles, esta ruta es única para el proyecto y no es accesible por otras aplicaciones por razones de seguridad.

On HTML5 exports, user:// will refer to a virtual filesystem stored on the device via IndexedDB. (Interaction with the main filesystem can still be performed through the JavaScriptBridge singleton.)

Convertir rutas a rutas absolutas o rutas "locales"

Puedes utilizar ProjectSettings.globalize_path() para convertir una ruta "local" como res://ruta/al/archivo.txt en una ruta absoluta del sistema operativo. Por ejemplo, ProjectSettings.globalize_path() se puede utilizar para abrir rutas "locales" en el administrador de archivos del sistema operativo utilizando OS.shell_open(), ya que este último solo acepta rutas nativas del sistema operativo.

Para convertir una ruta absoluta del sistema operativo a una ruta "local" que comience con res:// o user://, utiliza ProjectSettings.localize_path(). Esto solo funciona para rutas absolutas que apuntan a archivos o carpetas en la raíz de tu proyecto o en las carpetas user://.

Rutas de datos del editor

El editor utiliza rutas diferentes para los datos del editor, la configuración del editor y la caché, según la plataforma. De forma predeterminada, estas rutas son las siguientes:

Tipo

Localización

Datos del editor

Windows: %APPDATA%\Godot\
macOS: ~/Library/Application Support/Godot/
Linux: ~/.local/share/godot/

Ajustes del editor

Windows: %APPDATA%\Godot\
macOS: ~/Library/Application Support/Godot/
Linux: ~/.config/godot/

Cache

Windows: %TEMP%\Godot\
macOS: ~/Library/Caches/Godot/
Linux: ~/.cache/godot/
  • Datos del editor contiene plantillas de exportación y datos específicos del proyecto.

  • Configuración del editor contiene el archivo de configuración principal de la configuración del editor, así como varias otras personalizaciones específicas del usuario (diseños del editor, perfiles de características, plantillas de scripts, etc.).

  • Caché contiene datos generados por el editor o almacenados temporalmente. Puede eliminarse de forma segura cuando Godot se cierra.

Godot cumple con la XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html> en todas las plataformas. Las variables de entorno pueden ser anuladas según la especificación para cambiar las rutas de datos del editor y del proyecto.

Nota

Si usas Godot empaquetado como un Flatpak, las rutas de datos del editor se ubicarán en subcarpetas como ~/.var/app/org.godotengine.Godot/.

Modo autónomo

Si creas un archivo llamado ._sc_ o _sc_ en el mismo directorio que el ejecutable del editor (o en MacOS/Contents/ para un paquete .app del editor en macOS), Godot habilitará el modo autocontenido (self-contained mode). Este modo hace que Godot escriba todos los datos del editor, la configuración y la caché en un directorio llamado editor_data/ en el mismo directorio que el ejecutable del editor. Puedes utilizarlo para crear una instalación portátil del editor.

El Steam release of Godot utiliza el modo autónomo por defecto.

Nota

El modo autocontenido no es compatible con proyectos exportados por el momento. Para leer y escribir archivos en relación a la ruta del ejecutable, utiliza OS.get_executable_path(). Ten en cuenta que escribir archivos en la ruta del ejecutable solo funciona si el ejecutable se encuentra en una ubicación con permisos de escritura (es decir, no en Program Files u otro directorio que sea de solo lectura para los usuarios regulares).