CubicLauncher Themes

Repositorio comunitario de temas personalizados para CubicLauncher.

Estructura

src/
  Author/
    Theme/
      V1/
        Meta.toml
        Definition.toml
        bg.png              ← imagen de fondo
        fonts/
          Font.ttf
        Showcase.png        ← opcional, screenshot del autor
        changelog.md        ← opcional
      theme.md
      vflag.txt             ← opcional, verifica el theme completo (Solo agregado por el staff)

Cada tema vive bajo src/Author/Theme/ con subcarpetas versionadas (V1, V2, ...).

Los archivos binarios (imágenes, fuentes) se suben a Cloudflare R2 y no se almacenan en Git. El repositorio solo contiene archivos de texto (TOML, CSS, TXT, MD).

¿Cómo agregar un theme nuevo?

1. Creá src/TuAutor/TuTema/theme.md con la descripción.
2. Creá src/TuAutor/TuTema/V1/.
3. Agregá Meta.toml y Definition.toml (formato TOML de CubicLauncher).
4. Agregá bg.png (o .jpg, .gif, .webp) como imagen de fondo. Si el tema usa extends, podés omitirla.
5. Opcional: agregá Showcase.png, fuentes, changelog.md, etc.
6. Hacé commit y push a master.

El CI se encarga del resto automáticamente.

Herencia de temas (extends)

Un tema puede heredar los tokens de otro tema V2 de este repositorio. La base debe existir en src/ y el launcher debe tenerla instalada para poder aplicar el tema hijo.

En Meta.toml, siempre en la raíz:

name = "Bosque claro"
author = "tu_usuario"
version = "1.0.0"
format = 2
extends = "bosque_tu_usuario"

• extends usa el identificador instalado, no el nombre visible ni el slug del catálogo. Se calcula con name y author en minúsculas y espacios reemplazados por _: nombre_autor. Se acepta el prefijo user:.
• El tema base debe tener Meta.toml y Definition.toml (V2).
• El hijo gana clave a clave: lo que no define, lo hereda.
• Profundidad máxima: 8 niveles. Un ciclo es un error.
• El fondo (background.reference_path) es un asset del hijo y no se hereda; por eso un tema hijo puede no incluir bg.*.
• No se heredan fonts, icons, inject ni layout_pack porque sus rutas son relativas al tema que las declara.

themes.json expone extends (ID instalado) y extendsTheme (ID del tema base en el catálogo) por versión y en el nivel del tema.

Verificación de themes

El catálogo themes.json marca un theme con verified: true únicamente si existe un archivo llamado exactamente vflag.txt en src/Author/Theme/, junto a theme.md. Puede estar vacío: su contenido no se lee.

La verificación aplica al theme completo. Un directorio llamado vflag.txt o un archivo dentro de V1, V2, etc. no lo verifica. Sin el archivo, o al eliminarlo, el catálogo se genera con verified: false.

Agregar o quitar únicamente este flag actualiza el catálogo sin regenerar previews ni subir o eliminar assets en R2.

¿Cómo agregar solo un Showcase.png a un theme existente?

1. Agregá Showcase.png a src/Author/Theme/V1/Showcase.png.
2. Hacé commit y push a master.

El workflow sube el archivo a R2, actualiza showcaseUrl y preserva las URLs R2 existentes de los demás assets (bg, fuentes, etc.).

La preview se regenera automáticamente. Si bg.png no está en disco (ya fue subido a R2 en una ejecución anterior), la preview usará un gradiente como fallback.

CI — Workflow unificado

El workflow Generate + Assets to R2 corre en push a master y en PR cuando se modifican archivos en src/:

1. Detecta qué directorios de versión cambiaron (ej: src/4xnl/Jadol/V1).
2. Optimiza los PNGs nuevos con oxipng.
3. Genera previews solo para los directorios modificados (generate.js --dirs). Si cambia una base, también regenera los previews de los temas que la heredan.
4. Mergea collections externas a packages.json.
5. Sube a R2 los assets binarios nuevos, actualiza themes.json con URLs de R2, y borra los binarios locales (scripts/upload-assets.mjs).
   • Descubre automáticamente themes/versiones nuevos.
   • Preserva URLs R2 de assets que ya fueron subidos en ejecuciones anteriores.
6. Commit & push los cambios ([skip ci] para evitar loops).

Archivo de temas — Themes Archive

También existe un workflow manual Themes Archive Release en la pestaña Actions. Al ejecutarlo genera un release GitHub llamado archive-YYYY-MM-DD-HHMM (nunca "backup") que contiene un ZIP con todos los temas y todas sus versiones:

• Reconstruye src/ completo descargando los archivos de texto desde GitHub raw y los assets binarios desde R2.
• Adjunta themes.json, packages.json, README.md y LICENSE.
• Verifica que el ZIP no supere los 2 GB límite de GitHub antes de publicarlo.

Úsalo cuando quieras una copia comprimida completa del estado actual del repositorio.

Assets en R2

• Los binarios se suben a https://themes.cubiclauncher.org/ con nombres hasheados (file.<hash8>.ext) y Cache-Control: immutable.
• Los archivos de texto se sirven desde GitHub raw.
• El bucket R2 tiene CORS habilitado para permitir descargas desde el frontend.

Ejemplo:
  src/4xnl/Jadol/V1/bg.jpg
  → https://themes.cubiclauncher.org/src/4xnl/Jadol/V1/bg.132191b1.jpg

Licencia

CC0 1.0 Universal — dominio público.