Wiki / Getting Started / Tu Primer NPC

Tu Primer NPC

Aprende a crear un NPC con dialogos dinamicos generados por IA en menos de 10 minutos.

Prerrequisitos

Antes de comenzar, asegurate de tener:

  • ✔ OhMyDialogSystem instalado correctamente
  • ✔ Un modelo GGUF descargado y cargado
  • ✔ Godot 4.5 o superior
Si no tienes un modelo cargado, sigue primero la Guia de Inicio Rapido.
1

Paso 1: Crear CharacterIdentity

El recurso CharacterIdentity define la personalidad de tu NPC. Esta informacion se convierte en el system prompt que instruye al LLM.

  1. 1. En FileSystem, click derecho y selecciona New Resource
  2. 2. Busca y selecciona CharacterIdentity
  3. 3. Guarda el archivo como merchant.tres
  4. 4. Configura los campos en el Inspector:
Campo Valor de Ejemplo
character_name Nombre del personaje: Marcus the Merchant
personality Rasgos de personalidad: Friendly, shrewd, loves to haggle
background Historia del personaje: Former adventurer turned shopkeeper
speech_style Estilo de habla: MEDIEVAL
speech_patterns Muletillas o expresiones: ["By the coin!", "A fair deal..."]
knowledge Temas que conoce: Weapons, potions, local rumors
2

Paso 2: Script del NPC

Crea un script que use AIService para generar respuestas dinamicas basadas en la identidad del personaje.

Crea un nuevo script llamado npc_merchant.gd:

npc_merchant.gd GDScript 
extends CharacterBody3D

@export_file("*.tres") var character_identity_path: String

var _character: CharacterIdentity
var _ai_service: AIService
var _player_nearby: bool = false


func _ready() -> void:
    # Load character identity resource
    _character = load(character_identity_path)

    # Get AIService singleton
    _ai_service = AIService.get_singleton()

    if _character == null:
        push_error("CharacterIdentity not found!")


func _input(event: InputEvent) -> void:
    if event.is_action_pressed("interact") and _player_nearby:
        # Start dialogue with a greeting
        talk_to_player("Hello, what do you have for sale?")


func talk_to_player(player_message: String) -> void:
    if not _ai_service.is_model_loaded():
        push_error("No model loaded!")
        return

    # Build the prompt with character identity
    var system_prompt = _character.to_system_prompt()
    var llama = _ai_service.get_llama()

    # Generate response
    var response = llama.generate(player_message, system_prompt)

    print("[%s]: %s" % [_character.character_name, response])


func _on_detection_area_body_entered(body: Node3D) -> void:
    if body.is_in_group("player"):
        _player_nearby = true


func _on_detection_area_body_exited(body: Node3D) -> void:
    if body.is_in_group("player"):
        _player_nearby = false

Este script hace lo siguiente:

  • ▸ Carga el CharacterIdentity como recurso
  • ▸ Obtiene el singleton AIService
  • ▸ Usa to_system_prompt() para generar instrucciones para el LLM
  • ▸ Llama a generate() con el mensaje del jugador
3

Paso 3: Configurar la Escena

Configura la escena con un Area3D para detectar cuando el jugador se acerca al NPC.

Estructura de la escena:

Merchant (CharacterBody3D)
  └ MeshInstance3D # Visual representation
  └ CollisionShape3D # Physics collision
  └ DetectionArea (Area3D)
      └ CollisionShape3D # Interaction range (SphereShape3D, radius ~3m)
  1. 1. Agrega el script npc_merchant.gd al nodo raiz
  2. 2. Asigna la ruta del CharacterIdentity en character_identity_path
  3. 3. Conecta las senales body_entered y body_exited para detectar al jugador
4

Paso 4: Probar el Dialogo

Ejecuta la escena y prueba la interaccion con tu NPC.

  1. 1. Presiona F5 o ejecuta la escena
  2. 2. Acercate al NPC para activar el dialogo
  3. 3. Observa la consola para ver la respuesta generada
  4. 4. Experimenta con diferentes mensajes de entrada

Nota

La primera generacion puede tardar unos segundos mientras el modelo se calienta. Las siguientes respuestas seran mas rapidas.

Tips para Mejores Resultados

Personalidad Detallada

Cuanto mas detallada sea la personalidad en CharacterIdentity, mas consistentes seran las respuestas del NPC.

Patrones de Habla

Usa speech_patterns para agregar muletillas o expresiones unicas que hagan al personaje memorable.

Contexto del Mundo

Combina CharacterIdentity con WorldContext para que el NPC conozca el lore de tu juego.

Presets de IA

Usa AIPreset para ajustar la creatividad (temperature) segun el tipo de NPC.

Siguientes Pasos

Ahora que tienes tu primer NPC funcionando, explora estas guias:

← Volver al Inicio