Saltearse al contenido
Hytale Modding Manual

Roles de NPC

Descripción general

Un archivo de rol de NPC define todo sobre un NPC específico: su apariencia visual, estadísticas de salud y movimiento, rangos de detección, tablas de drops, membresía de manada, estado domesticable y el árbol de instrucciones de IA que dirige su comportamiento. Los roles son típicamente archivos Variant que heredan de una plantilla a través del patrón Reference + Modify, sobrescribiendo solo los campos que difieren de la plantilla base.

Ciclo de vida del rol de NPC

flowchart TD;
    A["Template File<br>e.g. Template_Beasts_Passive"] --> B["Role File<br>e.g. Chicken.json"];
    B -->|"Reference + Modify"| C[Resolved NPC Definition];


    C --> D[Spawn into World];
    D --> E[Idle State];


    E --> F{Detect Player?};
    F -->|"Passive NPC"| G["Continue Idle<br>or Wander"];
    F -->|"Hostile NPC"| H[Enter Combat];
    F -->|"Neutral NPC"| I{Was Attacked?};


    I -->|"No"| G;
    I -->|"Yes"| H;


    H --> J["Evaluate Actions<br>via Decision Making"];
    J --> K[Attack / Chase];
    J --> L[Flee / Retreat];
    J --> M[Use Ability];


    K --> N{Target Dead?};
    N -->|"Yes"| E;
    N -->|"No"| J;


    L --> O{Safe Distance?};
    O -->|"Yes"| E;
    O -->|"No"| L;


    G --> P{Take Damage?};
    P -->|"Yes, NPC is hostile"| H;
    P -->|"Yes, NPC flees"| L;
    P -->|"No"| E;


    style A fill:rebeccapurple,color:white;
    style B fill:steelblue,color:white;
    style H fill:darkred,color:white;
    style E fill:darkgreen,color:white;

Ubicación de archivos

Assets/Server/NPC/Roles/**/*.json

Los roles se organizan en subdirectorios por categoría:

  • _Core/ — Plantillas base y componentes compartidos
  • Aquatic/ — Peces, criaturas marinas
  • Avian/ — Aves
  • Boss/ — NPCs jefe
  • Creature/Critter/, Creature/Livestock/, Creature/Mammal/, Creature/Mythic/, Creature/Reptile/, Creature/Vermin/ — Animales del mundo abierto
  • Elemental/ — NPCs elementales
  • Intelligent/Aggressive/, Intelligent/Neutral/, Intelligent/Passive/ — NPCs de facciones y mercaderes
  • Undead/ — NPCs no muertos
  • Void/ — Criaturas del vacío

Esquema

Campos de nivel superior

FieldTypeRequiredDefaultDescripción
Type"Abstract" | "Variant" | "Generic"Sí—Abstract = plantilla base (no aparece en el mundo). Variant = hereda de un Reference. Generic = independiente, sin herencia.
ReferencestringPara Variant—El nombre de la plantilla de la que hereda este rol (p.ej. "Template_Predator").
ModifyobjectPara Variant—Campos a sobrescribir de la plantilla referenciada. Cualquier campo de nivel superior del rol puede aparecer aquí.
StartStatestringNoPredeterminado de plantillaEl nombre del estado inicial de IA (p.ej. "Idle").
AppearancestringNoPredeterminado de plantillaEl ID del modelo/rig a usar para este NPC. También puede establecerse vía { "Compute": "Appearance" } para extraerlo de Parameters.
MaxHealthnumber | ComputeNoPredeterminado de plantillaPuntos de vida máximos. A menudo se establece vía { "Compute": "MaxHealth" }.
MaxSpeednumberNoPredeterminado de plantillaVelocidad máxima de movimiento en bloques por segundo.
ViewRangenumberNoPredeterminado de plantillaRango de detección usando línea de visión, en bloques. Establece 0 para desactivar la vista.
ViewSectornumberNoPredeterminado de plantillaEl arco del campo de visión en grados (p.ej. 180 = medio hemisferio al frente).
HearingRangenumberNoPredeterminado de plantillaRango de detección usando sonido, en bloques. Establece 0 para desactivar la audición.
AlertedRangenumberNoPredeterminado de plantillaRango de detección extendido cuando el NPC ya es consciente de una amenaza, en bloques.
DropListstring | ComputeNoPredeterminado de plantillaID de la tabla de botín usada cuando este NPC es eliminado.
FlockArraystring[] | ComputeNo[]IDs de roles de NPC que pertenecen a este tipo de manada. Usado para comportamiento grupal coordinado.
AttractiveItemSetstring[] | ComputeNo[]IDs de objetos que atraen a este NPC cuando un jugador los sostiene cerca.
IsTameablebooleanNofalseSi este NPC puede ser domesticado por un jugador.
TameRoleChangestringNo—El ID de rol al que cambia cuando este NPC es domesticado exitosamente.
ProduceItemstringNo—ID del objeto producido por este NPC en un temporizador (p.ej. huevos de gallinas).
ProduceTimeout[string, string]No—Rango de duración ISO 8601 [min, max] entre ciclos de producción (p.ej. ["PT18H", "PT48H"]).
MemoriesCategorystring | ComputeNo"Other"Categoría usada por el sistema de memorias (p.ej. "Predator", "Undead", "Goblin").
NameTranslationKeystring | ComputeNo—Clave de traducción para el nombre visible del NPC (p.ej. "server.npcRoles.Fox.name").
ParametersobjectNo—Definiciones de parámetros con nombre con Value y Description. Usados con referencias { "Compute": "<key>" }.
InstructionsarrayNo—El árbol de instrucciones de IA. Cada entrada es un selector u objeto de paso evaluado en cada tick.
SensorsarrayNo—Configuración de sensores para detectar entidades y estado del mundo.
ActionsarrayNo—Lista de definiciones de acciones disponibles para la IA.
DisableDamageGroupsstring[]No—IDs de grupos de fuentes de daño que no pueden dañar a este NPC (p.ej. ["Self", "Player"]).
Invulnerableboolean | ComputeNofalseSi es true, el NPC no recibe daño.
KnockbackScalenumberNo1.0Multiplicador del retroceso recibido. 0 = sin retroceso.
MotionControllerListarrayNo—Controladores de física y locomoción (p.ej. Walk, Fly).
IsMemoryboolean | ComputeNofalseSi este NPC es rastreado en el sistema de memorias.
MemoriesNameOverridestring | ComputeNo""Sobrescribe el nombre mostrado en la memoria cuando se establece.
DefaultNPCAttitudestringNo—Actitud predeterminada hacia otros NPCs (p.ej. "Ignore", "Neutral").
DefaultPlayerAttitudestringNo—Actitud predeterminada hacia jugadores (p.ej. "Neutral", "Hostile").

Abreviación Compute

Cualquier campo que lee { "Compute": "ParameterKey" } resuelve su valor desde el bloque Parameters. Esto permite que las plantillas declaren valores predeterminados que los roles concretos pueden sobrescribir en su sección Modify.Parameters.

Ejemplos

Rol Variant (Zorro)

Hereda de Template_Predator y sobrescribe solo los campos específicos de un zorro.

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Fox",
    "DropList": "Drop_Fox",
    "MaxHealth": 38,
    "MaxSpeed": 8,
    "ViewRange": 12,
    "HearingRange": 8,
    "AlertedRange": 18,
    "AlertedTime": [2, 3],
    "FleeRange": 15,
    "IsMemory": true,
    "MemoriesCategory": "Predator",
    "NameTranslationKey": { "Compute": "NameTranslationKey" }
  },
  "Parameters": {
    "NameTranslationKey": {
      "Value": "server.npcRoles.Fox.name",
      "Description": "Translation key for NPC name display"
    }
  }
}

Rol de ganado con domesticación y producción (Gallina)

{
  "Type": "Variant",
  "Reference": "Template_Animal_Neutral",
  "Modify": {
    "Appearance": "Chicken",
    "FlockArray": ["Chicken", "Chicken_Chick"],
    "AttractiveItemSet": ["Plant_Crop_Corn_Item"],
    "AttractiveItemSetParticles": "Want_Food_Corn",
    "DropList": "Drop_Chicken",
    "MaxHealth": 29,
    "MaxSpeed": 5,
    "ViewRange": 8,
    "ViewSector": 300,
    "HearingRange": 4,
    "AlertedRange": 12,
    "AbsoluteDetectionRange": 1.5,
    "ProduceItem": "Food_Egg",
    "ProduceTimeout": ["PT18H", "PT48H"],
    "IsTameable": true,
    "TameRoleChange": "Tamed_Chicken",
    "IsMemory": true,
    "MemoriesNameOverride": "Chicken",
    "NameTranslationKey": { "Compute": "NameTranslationKey" }
  },
  "Parameters": {
    "NameTranslationKey": {
      "Value": "server.npcRoles.Chicken.name",
      "Description": "Translation key for NPC name display"
    }
  }
}

Rol Generic (Mercader Klops) — sin herencia de plantilla

{
  "Type": "Generic",
  "StartState": "Idle",
  "Appearance": "Klops_Merchant",
  "DropList": "Drop_Klops_Merchant",
  "MaxHealth": 74,
  "DefaultNPCAttitude": "Ignore",
  "DefaultPlayerAttitude": "Neutral",
  "NameTranslationKey": "server.npcRoles.Klops_Merchant.name"
}

Páginas relacionadas