[Mod/Framework] Universal Starting Beacon 1.2

Discuss and distribute tools and methods for modding. Moderator - Grognak
User avatar
kartoFlane
Posts: 1469
Joined: Mon Jan 14, 2013 10:20 pm

[Mod/Framework] Universal Starting Beacon 1.2

Postby kartoFlane » Mon Sep 09, 2013 9:51 am

.
About
--------

This is a trivially simple and small mod, whose intention is to provide a sort of a framework for other mods to work with.
It allows modders to create events that are only executed once at the start of the game.

While it's not hard to do this yourself, a standarized "framework" will allow greater compatibility between mods.

Why Would This Be Useful?
-----------------------------------

The problem with the START_GAME and START_BEACON is that the START_GAME event does nothing but replace the first beacon's <text> tag with its own. Its <choices> or <events> have no effect whatsoever.

START_BEACON, on the other hand, is triggered at the start of the game like you'd expect, but is also triggered every time the player enters a civillian sector. Initially, it just has its <text> replaced by the one in START_GAME.

To circumvent that, the mod changes the starting sector's starting event to its own custom one, that only happens once at the beginning of the game.


Why Should I Care?
-------------------------

It's an easy, ready solution to the problem. *shrug*

Also, with the advent of the preprocessed tags that Vhati and I have worked on, introduced in SMM 1.2, mods can be much more modular and hence more compatible with each other.

Agreeing on a common standard will benefit everyone.


How To Use
----------------

Tell people to download this framework and load it before your mod - do not include it in your mod, as that will cause it to overwrite previous mods and completely defeat the purpose of the framework.

Then, use one or both of the examples below in your mod, as you need them:

  • If your mod has some optional choices or actions you want the player to make at the beginning, append them to the START_GAME_CHOICES event:

    Code: Select all

    <mod:findName type="event" name="START_GAME_CHOICES">
      <mod-append:choice>
        <!-- Example -->
        <text>Go about your business</text>
        <event>
          <text>Suddenly, someone appears on your ship and demands to join your crew!</text>
          <crewMember amount="1" />
        </event>
      </mod-append:choice>
    </mod:findName>

  • If your mod has some important actions that are critical to your mod's workings, chain-load the START_GAME_BEACON event:

    Code: Select all

    <mod:findName type="event" name="START_GAME_BEACON">
      <!-- Proposed naming convention to keep things compatible and tidy -->
      <mod:setAttributes name="(mod-name)_START_GAME_BEACON" />
    </mod:findName>

    <event name="START_GAME_BEACON">
      <text>Example</text> <!-- You must have some text here, otherwise the choices are not loaded and the framework breaks entirely -->
      <choice>
        <text>Example</text>
        <event load="(mod-name)_START_GAME_BEACON" />
      </choice>
    </event>

Requirements
-------------------

This mod uses special pre-processed tags that were introduced in SMM 1.2 -- it will not work with GMM or previous versions of SMM.
As an extension, if you decide to use this, your mod will have the same requirements as this mod.

You can download Slipstream Mod Manager (SMM) here.


Download
-------------

[ Universal Starting Beacon 1.2 ]

For it to work correctly, load it before any other mods that use the framework, but after any mods that change the starting sector.


Changelog
--------------

Code: Select all

1.2
- fixed a bug that would prevent the START_GAME_CHOICES from being triggered whenever the START_GAME_BEACON was chain-loaded.
- this also fixed an issue where your START_GAME_BEACON's event text would not be visible if it happened to be the first event.
- if your START_GAME_BEACON has no event text, you need to give it one, otherwise the framework breaks.

1.15
- fixed a small bug that would prevent the framework from working

1.1
- split the single starting event into two separate events - one for appended choices, one for chain-loading.

1.0
- initial release
Last edited by kartoFlane on Sun May 15, 2016 1:15 pm, edited 11 times in total.
Superluminal2 - a ship editor for FTL
Vhati
Posts: 792
Joined: Thu Oct 25, 2012 12:01 pm

Re: [Mod/Framework] Universal Starting Beacon

Postby Vhati » Mon Sep 09, 2013 6:41 pm

Might want to elaborate on how the stock "START_GAME" and "START_BEACON" events work.
(or ways those names have been (ab)used in the past)

It'll clarify the need for adding "START_GAME_BEACON" to the modder lexicon.
http://xkcd.com/927/


Also, appending choices to an event will make each choice mutually exclusive.
Only the one that gets clicked will take effect, but the upside is you can choose which on each new game.

Chain-loading can be done against this event for mandatory stuff.
Vhati
Posts: 792
Joined: Thu Oct 25, 2012 12:01 pm

Re: [Mod/Framework] Universal Starting Beacon

Postby Vhati » Mon Sep 09, 2013 7:43 pm

Hmm, mixing several mods that use chain-loading and multiple-choice will have... odd effects. Depending on patch order, you could have chains with a choice to break the chain and do one other thing (then nothing else).


What about...
Reserve START_BEACON for chain-loading, and reserve START_CHOICE to append for multiple-choice.
And this universal framework mod could set the sectorDescription to a root START_BEACON that will load= an empty START_CHOICE.
Everyone who chains the former will eventually trigger the multiple-choice event last.
Everyone who appends choices to the latter will have them shown.


Also important: What's the maximum number of choices an event can have?
That'll cap the number of simultaneous multiple-choice mods, and how many choices each can add.

Hmm... That can be mitigated a little: since each mod's choice is mutually exclusive, they're free to append submenus of nested choices for themselves if desired (or append a choice to load= their submenu).
User avatar
kartoFlane
Posts: 1469
Joined: Mon Jan 14, 2013 10:20 pm

Re: [Mod/Framework] Universal Starting Beacon

Postby kartoFlane » Mon Sep 09, 2013 10:24 pm

Vhati wrote:Might want to elaborate on how the stock "START_GAME" and "START_BEACON" events work.
(or ways those names have been (ab)used in the past)

True, I should've done that. Will edit the OP to reflect that.

Vhati wrote:http://xkcd.com/927/

Gah - I had this xkcd stashed to use one day -- never thought it'd be used against me first :lol:

Vhati wrote:Also, appending choices to an event will make each choice mutually exclusive.
Only the one that gets clicked will take effect, but the upside is you can choose which on each new game.

That's precisely what I had in mind -- that way, you can load a bunch of ships that have starting game effects, and choose the choice intended for the ship you're playing.

Vhati wrote:What about...
Reserve START_BEACON for chain-loading, and reserve START_CHOICE to append for multiple-choice.
And this universal framework mod could set the sectorDescription to a root START_BEACON that will load= an empty START_CHOICE.
Everyone who chains the former will eventually trigger the multiple-choice event last.
Everyone who appends choices to the latter will have them shown.

The problem with the START_GAME and START_BEACON is that the START_GAME event does nothing but replace the first beacon's <text> tag with its own. Its <choices> or <events> have no effect whatsoever.

START_BEACON, on the other hand, works normally, but it is triggered every time the player enters a sector -- any sector. This is also the event that is triggered at the start of the game, and gets its <text> replaced by START_GAME.

To circumvent that, the mod changes the starting sector's starting event to the custom one.

Though I think what you mean is the following;

Code: Select all

<sectorDescription>
  <startEvent>START_GAME_BEACON</startEvent>
</sectorDescription>

<event name="START_GAME_BEACON">
  <event load="START_GAME_CHOICES" />
</event>
<event name="START_GAME_CHOICES">
  <text>*Should* still get replaced by START_GAME event</text>
</event>

Which would work pretty well, given the concern you brought up -- provided that no one confuses the two...

Vhati wrote:Also important: What's the maximum number of choices an event can have?
That'll cap the number of simultaneous multiple-choice mods, and how many choices each can add.

I'm not sure if there's a max, but more than 6-10 one-line choices will go out of the box bounds (depending on length of event text).
While it'll almost definitely happen, I don't think it'll be common sight for the event have so many choices.
Superluminal2 - a ship editor for FTL
Vhati
Posts: 792
Joined: Thu Oct 25, 2012 12:01 pm

Re: [Mod/Framework] Universal Starting Beacon 1.1

Postby Vhati » Mon Sep 09, 2013 11:28 pm

The 1.1 OP edit looks good.

Should change this line:
kartoFlane wrote:Just copy it and include in your mod - or tell people to download this and load alongside your mod.

to this:
Just copy either of these examples to include in your mod.
Then tell people to download this framework and load it before your mod.


Can't let those initial events get baked into mods.
Redeclaring them would clobber all the chains and appends.

Patch the framework once, early, and any number of dependent mods can follow, in any order.
User avatar
kartoFlane
Posts: 1469
Joined: Mon Jan 14, 2013 10:20 pm

Re: [Mod/Framework] Universal Starting Beacon 1.1

Postby kartoFlane » Tue Sep 10, 2013 12:21 am

Vhati wrote:Redeclaring them would clobber all the chains and appends.

Oh shi-- you're right. Gotta edit it ASAP.
Superluminal2 - a ship editor for FTL
User avatar
Kieve
Posts: 952
Joined: Tue Sep 18, 2012 2:21 pm
Location: Low Orbit
Contact:

Re: [Mod/Framework] Universal Starting Beacon 1.1

Postby Kieve » Tue Sep 10, 2013 12:39 am

... Events have never been my strong point to begin with, but this stuff is just frying every last cell in my cranium.
Maybe an example of what the hell I'm looking at so dummies like me can understand it a little better? :?
Vhati
Posts: 792
Joined: Thu Oct 25, 2012 12:01 pm

Re: [Mod/Framework] Universal Starting Beacon 1.1

Postby Vhati » Tue Sep 10, 2013 2:51 am

Kieve wrote:this stuff is just frying every last cell in my cranium.

Traditionally, you would write an entire named event, and that would obliterate any prior event that shared the name. If two or more mods wanted to claim an event, the last one would 'win'.


The new tags let you give instructions to edit existing XML.

This framework mod ensures two particular events will be available to modify, and that they will be triggered at the start of the game.

  • When you want to prompt players for an optional starting condition (eg, only relevant to a particular ship in the hangar), you can use a special tag to find an event named "START_GAME_CHOICES", and splice in a new choice of your own without completely replacing the event.

    The player will see all mods' choices side by side. After the player picks one, no further actions will be taken.

  • When you've got an important action to set up your mod at the start of the game, use a special tag to find the "START_GAME_BEACON" event, and change its name attribute to "MYNAME_START_GAME_BEACON" - just to move it out of the way. Then write your own "START_GAME_BEACON" event that will do something you want, then finish up with load="MYNAME_START_GAME_BEACON".

    Because your event has the normal name, it will be triggered as the game starts. Then yours will trigger the event that came before, and that will trigger the one that it preempted, and so on. Until the original event provided by this framework, which will show the multiple-choice event.

    * Technically it is possible to chain-load your own prompt with several responses, so long as all your choices ultimately continue the chain, but players may not like several mods' prompting one after another. Depends what you're asking.

Thus, mods can have their own events at the start without conflicting. The mods will all either edit the same event to add choices, or they'll sequentially load each other.


Some other tricks with the edit tags are mentioned in my announcement of SMM 1.2.
jep
Posts: 78
Joined: Mon Dec 02, 2013 3:19 am

Re: [Mod/Framework] Universal Starting Beacon 1.15

Postby jep » Thu Dec 12, 2013 6:56 pm

It occurs to me if SMM added a tag/method for performing an action if a given find FAILED, then this mod COULD be just mixed into your own mod without getting someone to add it separately.

Theoretical example:

Code: Select all


<!-- Chain-load this event if your mod's starting event is essential -->
<mod:findName invert="true" type="event" name="START_GAME_BEACON">
    <mod-append:event name="START_GAME_BEACON">
        <choice>
            <text>Continue...</text>
            <event load="START_GAME_CHOICES" />
        </choice>
    </mod-append:event>

    <!-- Append your start game <choices> or optional actions to this event -->
    <mod-append:event name="START_GAME_CHOICES">
        <text>You are about to set out on your journey.</text>
    </mod-append:event>
</mod:findName>


Okay, obviously this is a bit wonky but hopefully enough to get my point across. Basically, if it DIDN'T find an existing event named START_GAME_BEACON, it would add the standard one and add another event for START_GAME_CHOICES.

Then after this boilerplate, you'd do the normal appending/chaining like in the example in the first post. Does this make sense? If SMM could do this, you could just do away with the dependency and do everything in the individual mods without fear of clobbering.

The main downside I would see is if you wanted to make some changes in the base functionality and have them propagated out to everything that uses the mod. But given how insanely simple it is, I don't see that happening. And you COULD still do that, they'd just have to add the USB module and load it first. All the ones that used this method I outlined would still avoid clobbering the original USB.
jep
Posts: 78
Joined: Mon Dec 02, 2013 3:19 am

Re: [Mod/Framework] Universal Starting Beacon 1.15

Postby jep » Fri Dec 13, 2013 5:22 am

I ginned up some working code. Going to post in the SMM thread since it's more about SMM (though it would be good to use for USB, I think).

Who is online

Users browsing this forum: No registered users and 9 guests