Talking about programs

[BrunoMine]

I'd like to talk about how programs work.

Programs

The API follows an OS like model where "programs" are registered. Programs execute "instructions" and when a program is run it is put into a process queue (which is handled by a process scheduler that runs every 1 second). There is also the ability to interrupt processes in which the process state is stored. Also, processes have a variable storage if they need them.

Methods

• npc.programs.register(program_name, func): Register a program
• npc.programs.is_registered(program_name): Check if a program exists
• npc.programs.execute(luaentity, program_name, {program arguments}): Execute a program for a NPC

Program definition

{
    program_name = "modname:program1", -- Programs name

    arguments = {program arguments}, -- Arguments table for the program

    is_state_program = true, --[[
        ^ [OPTIONAL]
        ^ If this is true, then this program will be 
          repeated while there is no next program]]

    interrupt_options = {} -- [OPTIONAL] ???

    depends = {}, -- [OPTIONAL] ???

    chance = 75, -- [OPTIONAL] ???
}

This is part of the documentation that deals with programs. I would like @hkzorman to do a review and answer some questions.

The method npc.programs.execute does not especify some program definitions like depends and chance. That's true?

How do ??? definitions work?

[hkzorman]

Thanks for writing this.

Answering your questions:

• It's true that there are no depends or chance attributes in program or process definition. These are concepts that are exclusive to schedules.
• A small clarification: a program is a single, executable Lua function. A process is an instance of a program, with the following attributes:
  • A state, which can be any of:
    • inactive: process that was just enqueued
    • executing: process' Lua function is being executed and not finished yet
    • running: process finished execution, and may or may not have instructions on its queue
    • paused: interrupted process
    • ready: process was interrupted, and then restored, it is ready to run again
    • waiting_user_input: happens when on_rightclick interaction occurs
  • An instruction_queue, where instructions are enqueued and executed over time. In terms of OS, think of this as some kind of program counter
  • An execution_context, which is the data space of the process. The execution context is a map of key-value pairs, supporting read-only values (can't be updated again).
  • An interrupted_process, in case that this process interrupted a previous one, so that it can restored exactly as it was
  • An instruction state, where the current instruction being executed is stored as well as its state (so it can be re-executed in case process is interrupted)

The process definition is in private _exec.create_process_entry() function. This is like this so a process is always complete and ensured to have all its attributes. You can create a process entry and enqueue it into the NPC's process queue by using: npc.exec.enqueue_program(self, program_name, arguments, interrupt_options, is_state_program).

In the above, program_name is a string, arguments is a Lua table, interrupt_options is a Lua table (optional), and is_state_program is a boolean value (optional).

The exact process definition is this:

{
        id = process_id,
    program_name = program_name,
    arguments = arguments,
    state = npc.exec.proc.state.INACTIVE,
    execution_context = {
        data = {},
        instr_interval = 1,
        instr_timer = 0
    },
    instruction_queue = {},
    current_instruction = {
        entry = {},
        state = npc.exec.proc.instr.state.INACTIVE,
        pos = {}
    },
    interrupt_options = npc.exec.create_interrupt_options(interrupt_options),
    interrupted_process = {},
    is_state_process = is_state_program
}

The state process have an additional attribute and is_state_process is set to true:

state_process_id = os.time()

[BrunoMine]

Can you explain better about how the depends and interrupt_options definitions work?

Thanks for clarifications about the process.

[BrunoMine]

About npc.exec.enqueue_program command, do you think it should be in the same section of public methods programs? Or is it necessary to create a new session to handle the execution queue?

[hkzorman]

interrupt_options is a Lua table that defines what kind of interaction can interrupt the process when it is running. The "interruption" is not a literal process pause. It means that the defined interactions can happe while the process is running. In that fashion, for example, if the NPC is sleeping, talking (right click interaction) to the NPC can be disabled.

The three supported interaction types are defined below. They are all optional and accept values of true or false

• allow_punch: if enabled, the entity's on_punch() function is executed.
• allow_rightclick: if enabled, when the rightclick of the entitiy is called, the process is put on waiting_user_input state and entity's on_rightclick() executed
• allow_schedule: enables or disables schedule entries. If disabled, schedule will not run.

depends is a schedule entry concept. For a certain time, an array of programs is enqueued when the scheduled time arrives. The programs are enqueued in the order they are given in the array. If a program have a chance argument, it means that it could or couldn't happen. Therefore, some programs may or may not run, hence the depends.

depends is an array of numbers, where each number represents an index in the array of schedule entries for that time.

[hkzorman]

Regarding second question, if I understood correctly, you are asking if npc.exec.enqueue_program should be private or public. I believe it should public, otherwise there would be no way (apart from schedules) to enqueue programs.

[BrunoMine]

Perfect!