Mientras construyes un juego en Ren'Py, podrías notar algo.
play music "戦闘BGM.ogg"
Un nombre de archivo en japonés. Sin errores. Simplemente funciona.
Podrías pensar "Genial, usaré nombres de archivo en mi idioma nativo para gestionar mejor." Pero la respuesta corta es: no lo hagas. Esta guía explica por qué funciona, por qué es arriesgado y qué hacer en su lugar.
La respuesta corta: Funciona, pero es no oficial
En Ren'Py 8.5.2, usar caracteres no ASCII (japonés, chino, coreano, latín acentuado, etc.) en nombres de archivo de imagen, audio y video funciona en la mayoría de los sistemas.
Sin embargo, esta no es una característica oficialmente soportada. Tom Rothamel (PyTom), el creador de Ren'Py, ha declarado consistentemente en los Lemma Soft Forums:
Use ASCII in all filesystem object names. This makes distribution and cross-platform compatibility significantly easier.
La documentación oficial no contiene ninguna declaración de que los nombres de archivo Unicode sean compatibles.
Por qué funciona: Manejo de Unicode en Python 3
Entender por qué los nombres de archivo no ASCII funcionan requiere una breve lección de historia sobre Python.
La era de Python 2 (Ren'Py 6.x / 7.x)
En Python 2, las cadenas eran secuencias de bytes (str = bytes) por defecto. Para manejar texto no ASCII, necesitabas el prefijo u"" para crear explícitamente una cadena Unicode.
# Python 2 — esto es una cadena de bytes
"battle_bgm.ogg"
# Python 2 — esto es una cadena Unicode
u"戦闘BGM.ogg"
En Ren'Py 6.x, el manejo de archivos de audio pasaba los nombres de archivo a funciones C como char*, causando fallos UnicodeEncodeError con nombres no ASCII. Esto fue corregido en 2014, pero el manejo de cadenas de Python 2 seguía siendo fundamentalmente limitado.
La era de Python 3 (Ren'Py 8.x)
En Python 3, las cadenas son Unicode por defecto.
# Python 3 — esto ya es Unicode
"戦闘BGM.ogg"
El prefijo u"" ya no es necesario. Cada literal de cadena es nativamente Unicode. Ren'Py 8.x se ejecuta en Python 3.12, así que los problemas de codificación de la era de Python 2 simplemente no ocurren a nivel de cadena.
En otras palabras, Ren'Py no agregó soporte para nombres de archivo no ASCII — Python 3 hizo que Unicode fuera el predeterminado, y los nombres de archivo empezaron a funcionar como consecuencia.
Por qué es arriesgado: Tres formas en que la distribución falla
Funcionar en tu máquina de desarrollo y funcionar en la máquina de un jugador son dos cosas diferentes. Los nombres de archivo no ASCII tropiezan con tres minas durante la distribución.
Caso 1: Normalización Unicode en macOS
Los sistemas de archivos de macOS aplican normalización Unicode a los nombres de archivo. El antiguo HFS+ almacenaba los nombres en NFD (forma descompuesta), y el moderno APFS preserva la forma original en disco pero realiza comparaciones insensibles a la normalización internamente. Windows y Linux típicamente usan NFC (forma compuesta) y comparan los nombres byte a byte.
Por ejemplo, el carácter japonés "が" tiene dos representaciones internas:
| Forma | Representación | Descripción |
|---|---|---|
| NFC | が (1 carácter) | Compuesta. Estándar en Windows/Linux |
| NFD | か + ゙ (2 caracteres) | Descompuesta. Estándar en macOS HFS+ |
Un archivo almacenado como NFC 戦闘BGM.ogg en un ZIP puede ser normalizado de forma diferente en macOS. Cuando Ren'Py busca la secuencia exacta de bytes NFC, el archivo no se encuentra porque el sistema de archivos ve un nombre equivalente por normalización pero con bytes diferentes.
Este problema exacto fue reportado en el juego comercial de Ren'Py "WORLD END ECONOMiCA," donde un nombre de archivo japonés 飛び_右下.png no se cargaba en macOS.
Caso 2: Discrepancia de codificación en nombres de archivo ZIP
El sistema de compilación de Ren'Py produce archivos de distribución ZIP y tar.bz2. El formato ZIP no tiene una codificación de nombres de archivo estandarizada.
El módulo zipfile de Python 3 establece el flag UTF-8 (bit 11) al escribir, pero herramientas de extracción antiguas y algunas versiones de Windows Explorer ignoran este flag. El resultado: nombres de archivo ilegibles y un juego que no arranca.
Caso 3: Compilaciones Web y Android no están probadas
Ren'Py soporta compilaciones para navegador web (Emscripten/WebAssembly) y compilaciones APK para Android. Sin embargo, no hay confirmación oficial de que los nombres de archivo no ASCII funcionen correctamente en estas plataformas. Las compilaciones web tienen preocupaciones adicionales sobre las interacciones de codificación de URL HTTP.
La alternativa segura: Nombres de archivo ASCII + Alias
Mantén los nombres de archivo en ASCII y usa alias con define para legibilidad en tus scripts.
Archivos de audio
# Los archivos en audio/ usan nombres ASCII
# audio/battle_bgm.ogg
# audio/village_theme.ogg
# audio/rain_ambient.ogg
define audio.battle_bgm = "audio/battle_bgm.ogg"
define audio.village_theme = "audio/village_theme.ogg"
define audio.rain_ambient = "audio/rain_ambient.ogg"
label start:
play music battle_bgm
play sound rain_ambient
Crear alias en el espacio de nombres audio con define significa que nunca necesitas escribir rutas de archivo en las declaraciones play music. El nombre de la variable te dice qué es el audio, así que la legibilidad no es un problema.
Archivos de imagen
La detección automática de imágenes de Ren'Py mapea nombres de archivo separados por espacios a nombres de imagen (consulta la documentación de visualización de imágenes).
images/
├── bg forest.png → scene bg forest
├── bg castle.png → scene bg castle
├── eileen happy.png → show eileen happy
└── eileen sad.png → show eileen sad
Para definiciones manuales, mantén también el ASCII.
image bg forest = "images/bg_forest.png"
image bg castle = "images/bg_castle.png"
Convenciones de nomenclatura
Establecer reglas a nivel de proyecto mantiene las cosas manejables a medida que crece la cantidad de archivos.
# Audio
audio/{type}_{description}.ogg
audio/bgm_battle.ogg
audio/sfx_sword_slash.ogg
audio/amb_rain.ogg
# Fondos
images/bg {location}.png
images/bg forest.png
images/bg castle.png
# Personajes
images/{name} {expression}.png
images/eileen happy.png
images/eileen angry.png
FAQ
¿Puedo usar caracteres chinos, coreanos o latinos acentuados en nombres de archivo?
Sí, las mismas reglas aplican a todos los caracteres no ASCII — funcionan en desarrollo pero conllevan los mismos riesgos de distribución. La normalización de macOS afecta a los caracteres latinos acentuados (é, ñ, ü) tanto como a los caracteres CJK.
¿Los nombres de archivo no ASCII funcionan en Ren'Py 7.x?
Solo parcialmente. Ren'Py 7.x se ejecuta en Python 2, donde las cadenas son secuencias de bytes por defecto. El fix de 2014 resolvió los fallos de UnicodeEncodeError para archivos de audio, pero el soporte Unicode limitado de Python 2 hace que los nombres no ASCII sean aún más arriesgados que en 8.x.
¿Ren'Py soportará oficialmente nombres de archivo Unicode en el futuro?
No hay indicios de esto. PyTom ha recomendado consistentemente nombres de archivo ASCII en los Lemma Soft Forums, y la documentación oficial no menciona soporte para nombres de archivo Unicode. Dado que requeriría resolver problemas de normalización entre plataformas, el soporte oficial parece poco probable.
¿Los nombres de directorio con caracteres no ASCII causan los mismos problemas?
Sí. Los nombres de directorio pasan por las mismas operaciones del sistema de archivos que los nombres de archivo. Una ruta como images/キャラクター/eileen happy.png tiene tanto el nombre del directorio como el del archivo sujetos a problemas de normalización y codificación durante la distribución.
¿Puedo usar caracteres no ASCII en nombres de label o variables de Ren'Py?
Python 3 permite identificadores Unicode, así que label 戦闘シーン: técnicamente funciona. Sin embargo, el parser de scripts de Ren'Py puede no manejar todos los identificadores Unicode de forma consistente, y dificulta la colaboración con personas que no leen esos caracteres. Usa ASCII para los identificadores de código.
¿Cómo renombro archivos no ASCII existentes a ASCII de forma masiva?
Renombra los archivos con tu gestor de archivos o una herramienta de renombrado por lotes, luego actualiza todas las referencias en tus scripts .rpy. Busca el nombre de archivo antiguo en todo tu proyecto para no dejar ninguna referencia olvidada. Añadir alias define después del renombrado facilita los cambios futuros — solo necesitas actualizar una línea.
¿El problema de normalización de macOS afecta a APFS o solo a HFS+?
A ambos, aunque de forma diferente. HFS+ convertía forzosamente los nombres de archivo a NFD en disco. APFS preserva la secuencia de bytes original pero usa comparaciones insensibles a la normalización para las búsquedas. El resultado práctico es similar: un nombre de archivo escrito en NFC puede no coincidir con una búsqueda que espera igualdad exacta de bytes.
Conclusión
- ¿Funciona? — Los nombres de archivo no ASCII funcionan en Ren'Py 8.5.2 en la mayoría de los sistemas
- ¿Por qué? — El manejo nativo de cadenas Unicode de Python 3. No es una característica oficial de Ren'Py
- Riesgos — Normalización de macOS, discrepancias de codificación en ZIP, compilaciones Web/Android no probadas. La distribución puede fallar silenciosamente
- Recomendación — Nombres de archivo ASCII + alias
defineson seguros y prácticos
Para lo básico de Ren'Py, consulta la guía de inicio. Para detalles de configuración de audio, consulta la guía de audio.
Recursos oficiales:
- Ren'Py Documentation — referencia completa de todas las funciones
- Displaying Images — detección automática de imágenes y nomenclatura
- Audio — referencia de reproducción de audio
- Python 3 Unicode HOWTO — inmersión profunda en el modelo de cadenas de Python
- Documentación de Apple APFS — comportamiento de normalización de APFS
- r/RenPy — comunidad para preguntas y discusión
Artículos relacionados: