Add-on Getting Started/es: Difference between revisions

From DragonMineZ Wiki
EnglishEspañolPortuguês
← Older edit
VisualWikitext
Shokkoh (talk | contribs)
25,865 edits
Translation sync from dragonminez-wiki repository
Shokkoh (talk | contribs)
25,865 edits
Translation sync from dragonminez-wiki repository
 
(11 intermediate revisions by the same user not shown)
Line 21: Line 21:
| Java || <code>17</code> || Toolchain de <code>build.gradle.kts</code>
| Java || <code>17</code> || Toolchain de <code>build.gradle.kts</code>
|-
|-
| Mappings || <span lang="en" dir="ltr" class="mw-content-ltr">Parchment <code>2023.09.03-1.20.1</code></span> || <code>gradle.properties</code>
| Mappings || Parchment <code>2023.09.03-1.20.1</code> || <code>gradle.properties</code>
|-
|-
| GeckoLib || <code>4.8.3+</code> || <span lang="en" dir="ltr" class="mw-content-ltr"><code>gradle.properties</code>, add-on <code>mods.toml</code></span>
| GeckoLib || <code>4.8.3+</code> || <code>gradle.properties</code>, <code>mods.toml</code> del addon
|-
|-
| TerraBlender || <code>3.0.1.10+</code> || <span lang="en" dir="ltr" class="mw-content-ltr"><code>gradle.properties</code>, add-on <code>mods.toml</code></span>
| TerraBlender || <code>3.0.1.10+</code> || <code>gradle.properties</code>, <code>mods.toml</code> del addon
|-
|-
| Curios API || <span lang="en" dir="ltr" class="mw-content-ltr"><code>5.14.1+1.20.1</code> or newer</span> || <span lang="en" dir="ltr" class="mw-content-ltr"><code>gradle.properties</code>, add-on <code>mods.toml</code></span>
| Curios API || <code>5.14.1+1.20.1</code> o posterior || <code>gradle.properties</code>, <code>mods.toml</code> del addon
|}
|}


<div lang="en" dir="ltr" class="mw-content-ltr">
Usa exactamente estas versiones (o rangos de versiones compatibles) en el <code>build.gradle</code> o <code>build.gradle.kts</code>, el <code>gradle.properties</code> y el <code>mods.toml</code> de tu addon; si no, tendrás errores de carga de clases y de mixins incompatibles en tiempo de ejecución. DMZ está actualmente en la versión <code>2.2-alpha</code> del mod (<code>gradle.properties</code>).
Match these exactly (or with compatible version ranges) in your own add-on's <code>build.gradle</code> or <code>build.gradle.kts</code>, <code>gradle.properties</code> and <code>mods.toml</code>, or you will hit classloading and mixin mismatches at runtime. DMZ itself is currently on mod version <code>2.2-alpha</code> (<code>gradle.properties</code>).
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
GeckoLib, TerraBlender y Curios son dependencias '''obligatorias''' de DMZ, así que también deben estar en el classpath de ejecución de tu entorno de desarrollo.
GeckoLib, TerraBlender and Curios are '''mandatory''' dependencies of DMZ, so they must be on your development runtime classpath too.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="Incompatible_mods"></span>
== Incompatible mods ==
== Mods incompatibles ==
</div>
DMZ se niega a iniciar (lanza una <code>IllegalStateException</code> durante la carga) cuando alguno de estos mods está instalado, y los declara como <code>incompatible</code> en su <code>mods.toml</code>:
<div lang="en" dir="ltr" class="mw-content-ltr">
DMZ refuses to start (it throws an <code>IllegalStateException</code> while loading) when any of these mods is installed, and declares them <code>incompatible</code> in its <code>mods.toml</code>:
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
* Legendary Tooltips (<code>legendarytooltips</code>)
* Legendary Tooltips (<code>legendarytooltips</code>)
* Epic Fight (<code>epicfight</code>)
* Epic Fight (<code>epicfight</code>)
* Better Combat (<code>bettercombat</code>)
* Better Combat (<code>bettercombat</code>)
</div>
No dependas de ellos, no los incluyas ni los añadas a tus configuraciones de ejecución de desarrollo.
<div lang="en" dir="ltr" class="mw-content-ltr">
Don't depend on them, bundle them or add them to your development run configurations.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="Pre-release_builds"></span>
== Pre-release builds ==
== Versiones preliminares ==
</div>
<code>2.2-alpha</code> es una versión preliminar. Las versiones alpha y beta de DMZ solo dejan entrar a un mundo o servidor a los nombres de usuario de la lista blanca. El nombre de usuario de desarrollo predeterminado de ForgeGradle, <code>Dev</code>, está en la lista blanca, así que <code>runClient</code> funciona sin configurar nada: conserva ese nombre de usuario para tus pruebas locales.
<div lang="en" dir="ltr" class="mw-content-ltr">
<code>2.2-alpha</code> is a pre-release build. Alpha and beta builds of DMZ only let whitelisted usernames join a world or server. The default ForgeGradle development username <code>Dev</code> is on the whitelist, so <code>runClient</code> works out of the box: keep that username for local testing.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="Package_layout"></span>
== Package layout ==
== Estructura de paquetes ==
</div>
Antes de escribir código de hooks, échale un vistazo a la estructura del código fuente (<code>AI/Context.md</code> en el repositorio de DMZ la documenta en detalle):
<div lang="en" dir="ltr" class="mw-content-ltr">
* <code>com.dragonminez.client</code>: renderizado, GUI y animación; solo cliente.
Before writing any hook code, skim the source layout (<code>AI/Context.md</code> in the DMZ repository documents it in detail):
* <code>com.dragonminez.common</code>: configuración, estadísticas, red, misiones y deseos; la parte que más tocan los addons.
</div>
* <code>com.dragonminez.server</code>: comandos, almacenamiento, generación de mundo y eventos de servidor.
<div lang="en" dir="ltr" class="mw-content-ltr">
* <code>com.dragonminez.mixin</code>: mixins; evita depender de ellos desde un addon.
* <code>com.dragonminez.client</code>: rendering, GUI and animation; client only.
Los addons deberían engancharse casi exclusivamente a <code>com.dragonminez.common</code>: es la capa compartida y la más estable. Los únicos hooks del lado del cliente pensados para addons son <code>DMZClientEvent</code> y las ranuras del menú de utilidades (consulta [[Special:MyLanguage/Implementation and Events|Implementación y eventos]]).
* <code>com.dragonminez.common</code>: config, stats, networking, quests and wishes; the surface most add-ons touch.
* <code>com.dragonminez.server</code>: commands, storage, world generation and server events.
* <code>com.dragonminez.mixin</code>: mixins; avoid depending on these from an add-on.
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
Add-ons should hook <code>com.dragonminez.common</code> almost exclusively: it is the shared, most stable layer. The only client-side hooks meant for add-ons are <code>DMZClientEvent</code> and the utility menu slots (see [[Special:MyLanguage/Implementation and Events|Implementation and Events]]).
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="Two_integration_styles"></span>
== Two integration styles ==
== Dos formas de integración ==
</div>
# '''Dependencia obligatoria:''' tu addon necesita que DMZ esté presente (<code>mandatory=true</code> en <code>mods.toml</code>). Es la opción más simple, pero tu addon no cargará sin DMZ.
<div lang="en" dir="ltr" class="mw-content-ltr">
# '''Dependencia opcional:''' tu addon funciona por sí solo y únicamente activa el comportamiento específico de DMZ cuando detecta DMZ. DMZ usa este patrón para sus propias integraciones opcionales (<code>common/compat/WeaponLevelingCompat.java</code>, <code>common/compat/ApotheosisCompat.java</code>): comprueba <code>ModList.get().isLoaded("dragonminez")</code> una sola vez y deja toda clase que importe código de DMZ detrás de esa comprobación. Se recomienda si tu addon aporta algo sin DMZ instalado. Consulta [[Special:MyLanguage/Implementation and Events#Optional dependency pattern|Patrón de dependencia opcional]].
# '''Hard dependency:''' your add-on requires DMZ to be present (<code>mandatory=true</code> in <code>mods.toml</code>). This is the simplest option, but your add-on won't load without DMZ.
# '''Soft (optional) dependency:''' your add-on works on its own and only turns on DMZ-specific behavior when DMZ is detected. DMZ uses this pattern itself for its optional integrations (<code>common/compat/WeaponLevelingCompat.java</code>, <code>common/compat/ApotheosisCompat.java</code>): check <code>ModList.get().isLoaded("dragonminez")</code> once, and keep every class that imports DMZ code behind that check. This is recommended if your add-on has value without DMZ installed. See [[Special:MyLanguage/Implementation and Events#Optional dependency pattern|Optional dependency pattern]].
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="What_you_can_safely_rely_on"></span>
== What you can safely rely on ==
== En qué puedes confiar ==
</div>
* '''Eventos:''' las clases anidadas de <code>com.dragonminez.common.events.DMZEvent</code> (servidor y común) y <code>com.dragonminez.client.events.DMZClientEvent</code> (cliente) son la superficie pública de hooks prevista. Consulta [[Special:MyLanguage/Implementation and Events|Implementación y eventos]] para ver la lista completa.
<div lang="en" dir="ltr" class="mw-content-ltr">
* '''Estado del jugador de solo lectura:''' <code>StatsCapability</code>, <code>StatsProvider</code> y <code>StatsData</code>, para leer la raza, la forma, las estadísticas y los recursos.
* '''Events:''' the nested classes of <code>com.dragonminez.common.events.DMZEvent</code> (server and common) and <code>com.dragonminez.client.events.DMZClientEvent</code> (client) are the intended public hook surface. See [[Special:MyLanguage/Implementation and Events|Implementation and Events]] for the full list.
* '''Registros de extensión:''' <code>QuestObjectiveRegistry</code> y <code>QuestRewardRegistry</code> (tipos de contenido de misión personalizados), <code>DMZTextPlaceholders</code> (<code>%placeholders%</code> personalizados en textos de misiones y diálogos) y <code>UtilityMenuScreen.addMenuSlot</code> (botones en el menú de utilidades del cliente).
* '''Read-only player state:''' <code>StatsCapability</code>, <code>StatsProvider</code> and <code>StatsData</code>, for reading race, form, stats and resources.
* '''Registros:''' <code>MainItems</code>, <code>MainBlocks</code>, <code>MainEntities</code>, <code>MainAttributes</code>, <code>MainEffects</code>, <code>MainEnchants</code> (y las demás clases <code>Main*</code>) en <code>common/init/</code> exponen referencias <code>RegistryObject</code> y <code>DeferredRegister</code> que puedes importar directamente.
* '''Extension registries:''' <code>QuestObjectiveRegistry</code> and <code>QuestRewardRegistry</code> (custom quest content types), <code>DMZTextPlaceholders</code> (custom <code>%placeholders%</code> in quest and dialogue text) and <code>UtilityMenuScreen.addMenuSlot</code> (buttons in the client utility menu).
* '''Registries:''' <code>MainItems</code>, <code>MainBlocks</code>, <code>MainEntities</code>, <code>MainAttributes</code>, <code>MainEffects</code>, <code>MainEnchants</code> (and the other <code>Main*</code> classes) under <code>common/init/</code> expose <code>RegistryObject</code> and <code>DeferredRegister</code> references you can import directly.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="What_to_avoid_relying_on"></span>
== What to avoid relying on ==
== En qué no conviene confiar ==
</div>
* Los valores que envía el cliente para cualquier cosa relacionada con el progreso. DMZ tampoco confía en ellos; lee la capability del lado del servidor.
<div lang="en" dir="ltr" class="mw-content-ltr">
* Cambiar campos de <code>StatsData</code> directamente fuera de eventos o comandos. Es preferible reaccionar a los eventos o cancelarlos antes que tocar valores, y usar los comandos existentes de DMZ cuando necesites cambiar algo que pertenece a DMZ.
* Values reported by the client for anything related to progression. DMZ never trusts them either; read from the server-side capability instead.
* Registrar paquetes en el canal de red de DMZ. Los ids de paquete de DMZ dependen del orden de registro; usa tu propio canal.
* Changing <code>StatsData</code> fields directly outside of events or commands. Prefer reacting to or cancelling events over poking values, and prefer DMZ's existing commands when you need to change something DMZ owns.
* Depender de las clases de <code>com.dragonminez.mixin</code> o de partes internas de DMZ no mencionadas arriba. Pueden cambiar sin aviso entre versiones.
* Registering packets on DMZ's network channel. DMZ's packet ids depend on registration order; use your own channel.
* Depending on <code>com.dragonminez.mixin</code> classes or DMZ internals not mentioned above. These can change without notice between versions.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
<span id="Next_step"></span>
== Next step ==
== Siguiente paso ==
</div>
Cuando tu entorno de desarrollo compile contra DMZ y veas que lo detecta en tiempo de ejecución, pasa a [[Special:MyLanguage/Implementation and Events|Implementación y eventos]] para conectar los hooks reales y luego a [[Special:MyLanguage/Creating a DMZ Addon|Crear un addon de DMZ]] para la configuración completa de Gradle y <code>mods.toml</code>.
<div lang="en" dir="ltr" class="mw-content-ltr">
Once your development environment builds against DMZ and you can see it detected at runtime, move on to [[Special:MyLanguage/Implementation and Events|Implementation and Events]] to wire up actual hooks, then to [[Special:MyLanguage/Creating a DMZ Addon|Creating a DMZ Addon]] for the full Gradle and <code>mods.toml</code> setup.
</div>


{{Navbox Add-ons}}
{{Navbox Add-ons}}

Latest revision as of 22:26, 13 October 2026

Primeros pasos con addons explica lo que necesitas tener listo antes de conectar tu propio mod de Forge con DragonMineZ: las versiones de las herramientas, los mods que debes evitar y las partes de DMZ en las que un addon puede confiar sin riesgo. Léela antes de Crear un addon de DMZ.

Para quién es

Estas páginas son para desarrolladores de addons de Forge que quieren que el jar de su mod reaccione a DMZ: dar TP extra, escuchar cambios de forma, añadir nuevos tipos de objetivos y recompensas de misiones, agregar botones al menú de utilidades, etc. Si solo quieres ajustar números o añadir razas, formas, misiones o deseos, no necesitas nada de esto; consulta Alcance y requisitos.

DMZ no tiene una API de Java para registrar razas, formas, habilidades o técnicas nuevas: las razas y formas nuevas se añaden con archivos de configuración JSON (consulta Razas personalizadas y Formas personalizadas).

Herramientas necesarias

Requisito Versión Dónde se declara
Minecraft 1.20.1 gradle.properties
Forge 47.4.10 (acepta [47,)) gradle.properties, mods.toml del addon
ForgeGradle 6.0.30 Plugins de build.gradle.kts
Java 17 Toolchain de build.gradle.kts
Mappings Parchment 2023.09.03-1.20.1 gradle.properties
GeckoLib 4.8.3+ gradle.properties, mods.toml del addon
TerraBlender 3.0.1.10+ gradle.properties, mods.toml del addon
Curios API 5.14.1+1.20.1 o posterior gradle.properties, mods.toml del addon

Usa exactamente estas versiones (o rangos de versiones compatibles) en el build.gradle o build.gradle.kts, el gradle.properties y el mods.toml de tu addon; si no, tendrás errores de carga de clases y de mixins incompatibles en tiempo de ejecución. DMZ está actualmente en la versión 2.2-alpha del mod (gradle.properties).

GeckoLib, TerraBlender y Curios son dependencias obligatorias de DMZ, así que también deben estar en el classpath de ejecución de tu entorno de desarrollo.

Mods incompatibles

DMZ se niega a iniciar (lanza una IllegalStateException durante la carga) cuando alguno de estos mods está instalado, y los declara como incompatible en su mods.toml:

  • Legendary Tooltips (legendarytooltips)
  • Epic Fight (epicfight)
  • Better Combat (bettercombat)

No dependas de ellos, no los incluyas ni los añadas a tus configuraciones de ejecución de desarrollo.

Versiones preliminares

2.2-alpha es una versión preliminar. Las versiones alpha y beta de DMZ solo dejan entrar a un mundo o servidor a los nombres de usuario de la lista blanca. El nombre de usuario de desarrollo predeterminado de ForgeGradle, Dev, está en la lista blanca, así que runClient funciona sin configurar nada: conserva ese nombre de usuario para tus pruebas locales.

Estructura de paquetes

Antes de escribir código de hooks, échale un vistazo a la estructura del código fuente (AI/Context.md en el repositorio de DMZ la documenta en detalle):

  • com.dragonminez.client: renderizado, GUI y animación; solo cliente.
  • com.dragonminez.common: configuración, estadísticas, red, misiones y deseos; la parte que más tocan los addons.
  • com.dragonminez.server: comandos, almacenamiento, generación de mundo y eventos de servidor.
  • com.dragonminez.mixin: mixins; evita depender de ellos desde un addon.

Los addons deberían engancharse casi exclusivamente a com.dragonminez.common: es la capa compartida y la más estable. Los únicos hooks del lado del cliente pensados para addons son DMZClientEvent y las ranuras del menú de utilidades (consulta Implementación y eventos).

Dos formas de integración

  1. Dependencia obligatoria: tu addon necesita que DMZ esté presente (mandatory=true en mods.toml). Es la opción más simple, pero tu addon no cargará sin DMZ.
  2. Dependencia opcional: tu addon funciona por sí solo y únicamente activa el comportamiento específico de DMZ cuando detecta DMZ. DMZ usa este patrón para sus propias integraciones opcionales (common/compat/WeaponLevelingCompat.java, common/compat/ApotheosisCompat.java): comprueba ModList.get().isLoaded("dragonminez") una sola vez y deja toda clase que importe código de DMZ detrás de esa comprobación. Se recomienda si tu addon aporta algo sin DMZ instalado. Consulta Patrón de dependencia opcional.

En qué puedes confiar

  • Eventos: las clases anidadas de com.dragonminez.common.events.DMZEvent (servidor y común) y com.dragonminez.client.events.DMZClientEvent (cliente) son la superficie pública de hooks prevista. Consulta Implementación y eventos para ver la lista completa.
  • Estado del jugador de solo lectura: StatsCapability, StatsProvider y StatsData, para leer la raza, la forma, las estadísticas y los recursos.
  • Registros de extensión: QuestObjectiveRegistry y QuestRewardRegistry (tipos de contenido de misión personalizados), DMZTextPlaceholders (%placeholders% personalizados en textos de misiones y diálogos) y UtilityMenuScreen.addMenuSlot (botones en el menú de utilidades del cliente).
  • Registros: MainItems, MainBlocks, MainEntities, MainAttributes, MainEffects, MainEnchants (y las demás clases Main*) en common/init/ exponen referencias RegistryObject y DeferredRegister que puedes importar directamente.

En qué no conviene confiar

  • Los valores que envía el cliente para cualquier cosa relacionada con el progreso. DMZ tampoco confía en ellos; lee la capability del lado del servidor.
  • Cambiar campos de StatsData directamente fuera de eventos o comandos. Es preferible reaccionar a los eventos o cancelarlos antes que tocar valores, y usar los comandos existentes de DMZ cuando necesites cambiar algo que pertenece a DMZ.
  • Registrar paquetes en el canal de red de DMZ. Los ids de paquete de DMZ dependen del orden de registro; usa tu propio canal.
  • Depender de las clases de com.dragonminez.mixin o de partes internas de DMZ no mencionadas arriba. Pueden cambiar sin aviso entre versiones.

Siguiente paso

Cuando tu entorno de desarrollo compile contra DMZ y veas que lo detecta en tiempo de ejecución, pasa a Implementación y eventos para conectar los hooks reales y luego a Crear un addon de DMZ para la configuración completa de Gradle y mods.toml.

Retrieved from "https://wiki.dragonminez.com/es/wiki/Add-on_Getting_Started?oldid=13596"