Fundamentals of spawning agents in scenes [solved + explanation]

[Kahsm]

Disclaimer: I just read the module documentation to start scripting 2 days ago.

Alrighty, I've been reading troop tuples, scripts, game menus, and mission templates for hours now and I still don't quite understand how agents are spawned on their entry points. I feel like I should know, but my experimentation doesn't work out the way I expect, so I hope someone can fill me in on what I'm missing.

If you want to quickly explain the process from creating a single hero agent troop (like an arena master) and spawning him in a single castle, please do. However, if you're more of a reader, i've 'spoiler-ed' my experiments and some of what I already believe I know, and you can comment directly on that.

However, one last thing.  This question is not about how to get my code to work. I am more interested in why it doesn't work, and how the system works in whole. Given that, I can extrapolate future answers.

This means the answer I do not want is: If in Sargoth... (set_visitor, 1, :dude),
I know how to do that already.

Unless of course that's the ONLY way, but obviously there are many agents that don't get added that way.

Spoiler

To make my unique, yet static, agent.. he needs to be a hero troop. So I made the dude, and he's the very last entry in the troop list.

["town_1_dude","Dude","{!}Dude",tf_hero|tf_randomize_face, scn_town_1_castle|entry(1), reserved, fac_commoners,[itm_leather_jerkin,itm_hide_boots],def_attrib|level(2),wp(20),knows_common,0x0000000d0d1030c74ae8d661b651c6840000000000000e220000000000000000],

As you can see, I want him to spawn in town #1's castle, entry point #1.  Sargoth's castle doesn't actually have an entry point 1 defined in the scenes, so I made one. That was pretty easy. The "visit_town_castle" mission template, however, already has the a spawn record for entry_point 1 defined.

(1,mtef_scene_source|mtef_team_0,af_override_horse,0,1,[]),

I see that it's a scene_source, and I saw in another thread during my pre-question-searching that scene_source is what you want for agents with defined locations like my 'Dude'.  Just so you know, I've also tried spawning him at existing entry points in various scenes (like the arena and tavern).

At this point I originally thought that the game engine would just say, "alright he wants that guy in that scene at that point, and we know that point exists, so just do it!" Well it obviously doesn't work that way. So where do I look next? Well, I went to the closest working actor to the one I'm trying to emulate, and that's the Arena Master.

First though, why not the merchants or the tavern keeper? Well because they don't have pre-set locations. The Arena Master does.  If someone wants to explain why that is, please do.  I can see in the scripts that Armorer, Tavernkeeper, Weaponsmith, and Merchant all get added in the Town Loop. I still haven't found the exact moment they are created at their spawn points, but I can imagine how that process works  once you have all the troop IDs saved in the town's Party slots via the following from module_scripts: (not that my imagination has been right yet)

# Towns (loop)
      (try_for_range, ":town_no", towns_begin, towns_end),
        (store_sub, ":offset", ":town_no", towns_begin),
        (party_set_slot,":town_no", slot_party_type, spt_town),

  #[... removed some code to keep this shorter ...]

        (store_add, ":cur_object_no", "trp_town_1_mayor", ":offset"),
        (party_set_slot,":town_no", slot_town_elder, ":cur_object_no"),
        (store_add, ":cur_object_no", "trp_town_1_tavernkeeper", ":offset"),
        (party_set_slot,":town_no", slot_town_tavernkeeper, ":cur_object_no"), <---
        (store_add, ":cur_object_no", "trp_town_1_weaponsmith", ":offset"),
        (party_set_slot,":town_no", slot_town_weaponsmith, ":cur_object_no"),
        (store_add, ":cur_object_no", "trp_town_1_armorer", ":offset"),
        (party_set_slot,":town_no", slot_town_armorer, ":cur_object_no"),
        (store_add, ":cur_object_no", "trp_town_1_merchant", ":offset"),
        (party_set_slot,":town_no", slot_town_merchant, ":cur_object_no"),
        (store_add, ":cur_object_no", "trp_town_1_horse_merchant", ":offset"),
        (party_set_slot,":town_no", slot_town_horse_merchant, ":cur_object_no"),
        (store_add, ":cur_object_no", "scn_town_1_center", ":offset"),
        (party_set_slot,":town_no", slot_town_center, ":cur_object_no"),
        (party_set_slot,":town_no", slot_town_reinforcement_party_template, "pt_center_reinforcements"),
      (try_end),

At the arrowed line, you can see one of the town's party slots is given the troopID for their particular tavernkeeper's troop, but Arena Masters are not managed this way, despite having an arena master in every town, just like innkeepers.  So then I decided to look at the game_menu for entering the arena to see if he's manually inserted:

"Enter the arena.",
       [
           (try_begin),
             (this_or_next|eq,"$all_doors_locked",1),
             (eq,"$town_nighttime",1),
             (display_message,"str_door_locked",0xFFFFAAAA),
           (else_try),
             (assign, "$g_mt_mode", abm_visit),
             (assign, "$town_entered", 1),
             (set_jump_mission, "mt_arena_melee_fight"),      <---- 1
             (party_get_slot, ":arena_scene", "$current_town", slot_town_arena),
             (modify_visitors_at_site, ":arena_scene"),
             (reset_visitors),                                                <----- 2
             (set_visitor, 43, "trp_veteran_fighter"),    <---- 3
             (set_visitor, 44, "trp_hired_blade"),
             (set_jump_entry, 50),                                  <----- 4
             (jump_to_scene, ":arena_scene"),
             (scene_set_slot, ":arena_scene", slot_scene_visited, 1),
             (change_screen_mission),
           (try_end),
        ],"Door to the arena."),

At arrow 1, I can see that it uses the melee fight mission_template to define the entry points. But then at arrow 2 it resets the visitors -- I'm not sure what this does. Does it remove all the default spawned ones? That would explain a lot if it did. Actually, let me try removing that to see what it does, give me a moment........ nothing changes, figured -- continuing on! So at arrow 3, I can see the demo combatants are added in the arena, then at arrow 4 it seems to jump the spawn iterator to 50?

Originally I thought the entry jump was so that anyone spawned after this point would be "upstairs" since the Arena Master is on entry_point 52, but 53 is actually back down in the arena, so I'm not sure what the point of that is. Furthermore, I see no place where the arena master himself is spawned.

But then, of course he's not spawned explicitly like the combatants, it would be silly to have defined the exact location in the troop file, just to then manually assign that troop to that entry point again in the game_menu -- doesn't make sense.

I ran some multi-file searches to find some other place in maybe scripts or triggers that mention "arena" or "arena master" or something of that ilk in *.py to no success. So I have no idea where he's spawned. I assume it's hidden in some trigger somewhere.

I'm just creating more questions than I'm getting answers to, and getting away from my original purpose. And that's perfectly fine, I'm learning the system very thoroughly as I go through all these pieces, scripts, and files. But my main question still remains: If I define a scene_location|entry(#) for a hero troop, why doesn't that troop get created at that entry_point in that scene?

So to see how important that location definition is I removed it from the Arena Master in Sargoth only.

["town_1_arena_master", "Bobby II         ","{!}Tournament Master",tf_hero|tf_randomize_face, 0                         ,reserved,   fac_commoners, ...
["town_2_arena_master", "Tournament Master","{!}Tournament Master",tf_hero|tf_randomize_face, scn_town_2_arena|entry(52),reserved,   fac_commoners ...
["town_3_arena_master", "Tournament Master","{!}Tournament Master",tf_hero|tf_randomize_face, scn_town_3_arena|entry(52),reserved,   fac_commoners ...

(btw his name is "Bobby II" because I change his name eveyr time i change something so I know the new compile is actually in, if you were wondering if that might be the problem -- it's not)

I think a rational person would expect him to disappear, since he no longer has a location defined. Guess what? he doesn't! Nor does he spawn in some random spot, or in entry_point 50 where I thought the jump moved some sort of spawning iterator. He's right at #52.  So now I'm wondering if this whole scene_location|entry(#) thing is depreciated?  I know the module documentation is pretty old.  And if that's the case, is adding my hero within a conditional in the mission_template or menu_dialog for entering the Sargoth Court the best(only) way to do it?

Of course, that then brings me back to... how the hell does the arena master get spawned? My head hurts. I hope I've done my due diligence, and I'd love some advice.

Edit: Added self-deprecating humour

 

[Caba`drin]

To start, classy avatar.

Now, to the fundamentals.

Concerning entry points.
mtef_scene_source as the flag for entry point one will not be compatible with your "set_visitor" command. To spawn your agent, based on the "town_1_dude" troop, with the set_visitor operation you need to use one of the entry points that are flagged mtef_visitor_source. I recommend picking one that is already universally used/existent for simplicity's sake. You can find used entry points in module_game_menus, in the "town" menu. I would focus my energy in understanding the processes in the "town" menu...specifically the options for walking around the streets and for entering the tavern, as those are what you'll be using I believe.

"set_jump_entry" gives the entry point for the player upon entering the scene and mission.

So far as how is the arena master spawned, you'll note that the arena masters are the only troops that use the "scn_town_1_arena|entry(52)" flags in their troop declaration. You'll also notice in the arena mission templates, entry point #52 is flagged mtef_scene_source. Thus, it isn't touched when visitors are reset.

With what you've tried, your problem may be that you are trying to use entry point 1...which is used by the player. You may wish to try another entry, or move away from the troop file entry definitions to a menu-based system that is used for pretty much everything but the arena masters.

The easiest way to add other agents is to duplicate the code spawning similar agents. So if you want this dude to be like a mercenary in a tavern, see how they are added to taverns, etc. In that fashion, you'd do the entry via the menu...you'll want a small try block in the appropriate menu option of the "town" menu, which you've mentioned you've figured out. I think your difficulty comes down to "scene_source" and "visitor_source" entry points.

 

[Kahsm]

Thanks for the reply! Away from my comp, but I want to do a prelim response for anyone else who may comment before I can try out some new ideas you generated.

I _believe_ the player's entry was 0 there was no entry_point 1 in the object list in the castle scene before I added it. And I did try other points. I tried 27 originally, and changed it from a visitor_source to scene_source in the mission_template with no success.

I understand that changing the visitors in scripts/triggers/dialog doesn't affect the scene_sourced agents, which is why the arena master doesn't need to be explicitly placed as if he were a visitor. However, that doesn't explain how scene_sourced actor spawning works in the first place. And why when I removed Sargoth's Arena Master's scene|entry() data, that he still showed up in the right spot. That said, you are quite correct about trying to use set_visitor on a scene_source. Though I'm hoping to avoid using it all together.

I do take your point that my goal is like mercs in the tavern. And I could, and likely will, do it that way. But it still bothers me that scene|entry() doesn't seem to work as I expect it to.

A new thought I had. In the module documentation where an agent is spawned into an inn using a simple scene|entry() reference, that troop had a 'physical' manifestation, it was in a party. Could that be the difference? The scene can't create new agents maybe, just place existing ones. Might be worth looking at the code that randomizes potential companions amongst the inns, because I'm kind of looking for a stationary version of that.... just a thought to try tomorrow.

 

[Somebody]

Troops are essentially agent templates. You do not need one in any party for an agent to inherit equipment and health (if tf_hero is marked). Visitors must be placed before you actually enter a scene, after that they can only be instantiated with spawn_agent or added with add_visitors_to_current_scene. The feature is vestigial, but not deprecated. It's also likely that the location information is preserved in savegames, but I assumed you renamed the NPC to ensure it refreshed.

 

[Kahsm]

Alrighty, so I figured it out.

Turns out my initial assumptions were correct, I just didn't start a new game at the appropriate moment to see it working. For all those who use conditionals in the scripts/game_menus on entering certain scenes of certain cities to place specific troops could also use this extremely easy scene_source method.

I don't intend this to be a detailed tutorial, just a quick summation of the process as I currently understand it. Feel free to call out my misinterpretations.

Step 1: Add your hero NPC to the troop list, as per usual, but add the location information like the native tournament masters. For example: "scn_town_1_castle|entry(#)", where # is an entry point already existing in, or one you added to, the target scene.

Step 2: Scenes are often used for multiple purposes. For example, you can enter an arena in the default fashion, as if you want to start one of the endurance fights, or you can enter the same arena scene to participate in various types of tournament fights.  So you need to locate all the templates in module_mission_templates which "initialize" the scene's entry points for all the situations where you want your NPC to show up. So for my castle example, I locate "visit_town_castle" and see a fairly straight-forward list of entry point initializations that look like this:

...
(2,mtef_scene_source|mtef_team_0,af_override_horse,0,1,[]),
...
(21,mtef_visitor_source,af_castle_lord,0,1,[])
...

The number after the opening brace is the entry point number, and I've shown one example of each entry point type, mtef_scene_source and mtef_visitor_source.  The constants, variables, and tuples after those first two fields set various things that change the equipment or behavior of the spawned npc, I won't get into those any further.

For our purposes, spawning a single hero npc to stand around in a specific castle, all you need to do is ensure that a) your entry point is in this list, and b) that the entry point is defined as mtef_scene_source.  This tells the game that the entry point is predefined for an npc.  As an example, entry point 0 for most, if not all, templates is defined as mtef_scene_source because that is where the player enters. No visitors will take that spot.

Side Note: If it's not obvious by the mission_template name (some of them are not), you can find the appropriate template by following the game_menus or scripts that lead your character to entering that scene. For example, in game_menus you'll find that the "Go to castle" menu item calls "enter court" in module_scripts, that script contains this line:

(set_jump_mission,"mt_visit_town_castle"),

And that is your mission template for visiting a town's castle which contains the entry point initializations.

Crucial Step 3: Start a new game. It seems the positions of scene-defined NPCs are saved to existing game saves.  Even though I can change almost everything about a troop without reloading, their position won't change if you're using this scene_source method.

 

[Somebody]

Defining their initial scene and entry point should be similar to using add_troop_to_site.