Page 1 of 2 12 Last
  1. #1

    Join Date
    Apr 2007
    Location
    Mississippi, USA
    Posts
    491

    [Tutorial] Creating a Basic Extension

    To start you should plan out what you want your extension to do. Its also helpful to unzip several pre-made extensions and rule sets to see how things are done in them. To do this copy the rule set or extension out of the rule set or extenstion folder into a location outside the Fantasy Grounds folder. Then rename the file from *.pak or *.ext to *.zip. Then open it as you would a normal zip file. Extract those files to a location you can easily get to. Then open those files in your favorite reader (I use Notepad++).

    An extension is based on the same code as a rule set, but it supersedes the code in a rule set. This is helpful because you can override entire files in a ruleset or simply override a few widgets or pieces of code.

    What you need to do next is create a folder in your Fantasy Grounds extensions folder:
    <drive letter>:\Users\<username>\AppData\Roaming\Fantasy Grounds\extensions\<extension folder name>

    After you create the folder, next you need to create an xml file called 'extension' in that folder. More information can be found here. Then we fill in the xml file with the following:

    Code:
    <?xml version="1.0" encoding="iso-8859-1"?>
    <root version="3.3" release="1.0">
    	<announcement text="Text that is displayed on start of ruleset. Usually the extension name and copyright info." font="emotefont" />
    	<properties>
    		<name>Name of Extension</name>
    		<version>0.1(version of extension)</version>
    		<author>Author of Extension</author>
    		<description>A description of the extension.</description>
    	</properties>
    	<base>
    		<!-- This file is our main Lua file. You can name it what you want, but you must use xml restrictions in order to do that.-->
    		<script name="ScriptPackageName" file="scripts/scriptFileName.lua" />
    	</base>
    </root>
    Once you have this done, you can begin coding the extension in the script file that you created. To access your script files functions and global variables you'll use the 'name=' attribute of the <script> tag, in this case it is "ScriptPackageName". This is useful if you have to put scripts in other locations such as within xml tags within other file locations that you are overriding (such as the example xml file of "campaign/campaign_images.xml"). Sometimes you will need to put scripts within xml tags in order to have certain functions and callbacks work properly.

    A good practice is to keep all of your global variables in your main Lua file (in this case "ScriptPackageName") and access them from the custom script locations, because it is difficult to derive a package name to where those other scripts are located (and likely have to be done at run time due to 'instances' of those packages and classes).

    Our Lua file should look like this:

    Code:
    --
    --  Copyright James (Lokiare) Holloway 2014+ except where explicitly stated otherwise.
    -- Fantasy Grounds is Copyright  2004-2014 SmiteWorks USA LLC.
    -- Copyright to other material within this file may be held by other Individuals and/or Entities.
    -- Nothing in or from this LUA file in printed, electronic and/or any other form may be used, copied,
    --	transmitted or otherwise manipulated in ANY way without the explicit written consent of
    --	James (Lokiare) Holloway or, where applicable, any and all other Copyright holders.
    --
    You'll want to put your copyright info and the copyright info of SmiteWorks first using the comment tags "--". This will help protect SmiteWorks and yourself from any kind of lawsuit or copyright theft.

    Code:
    -- Global Variables for this package
    count = 0;
    Global variables can be accessed in other packages by using the package name and a '.' and then the global variable name (for instance: "ScriptPackageName.count" for the above variable). In this Lua file package they can be accessed just using the variable name "count". Variables in Lua aren't typed, so you don't have to know what's in a variable to use it or assign it.

    To keep this simple I'm going to make an extension for 4E that allows you to send some text to the chat window on the start of someones turn. This text will include the name of the character who's turn it is and the number of rounds that have gone by. In order to do this we have to find out who's turn it is on the combat tracker.

    Code:
    function getTokenInfo(nodeEntry)
    	-- This is the structure of Fantasy Grounds chat messages. Sender is who it shows as sending the message. Font is the font used to display the message. Icon is the special fantasy grounds icon displayed next to the sender. You can assign special icons, but that is beyond the scope of this tutorial.
    	local msg = {sender = "Zones", font = "emotefont", icon = "turn_flag"};
    	msg.text = "";
    	-- Get the current characters name (check to make sure the nodeEntry is not nil)
    	if nodeEntry then
    		-- Here we use the ActorManager to get the actor from the Combat Tracker based on the node entry that is passed into the function.
    		local rActor = ActorManager.getActorFromCT(nodeEntry);
    		-- We set the message text to be equal to the actors name.
    		msg.text = rActor.sName;
    	end
    	-- Return the msg that we created so it can be used to display the message to the chat panel.
    	return msg;
    end
    Now that we know who's turn it is and we return that information in a msg object (all variables are really tables in Lua). We need to use a callback in order to have Fantasy Grounds trigger the action on the start of a turn. For more functions and callbacks refer to the rule set reference guide. Some specific functions and callbacks may not be detailed there, but you can find them specifically in the rule set .pak file that they belong to. The rule set reference guide mainly covers the core Rule set that all other rule sets are based on.

    Code:
    -- This function is one that the Combat Tracker calls if present at the start of a creatures turn.
    function onTurnStartEvent(nodeEntry)
    	-- Here again we create a msg and call the getTokenInfo function that we created earlier to get a message with the creatures name whose turn it is.
    	local msg = getTokenInfo(nodeEntry);
    	-- We concatenate several strings onto it using '..' the Lua concatenation symbols for strings. (its useful because it tries to convert whatever you are putting together into a string.
    	msg.text = "Its " .. msg.text .. "s turn.";
    	--Here we call the Comm package to send the message to the chat. We use deliverChatMessage in order to have it echoed to the clients that are connected.
    	-- Iterate the count
    	count = count + 1;
    	-- Add the count to the message
    	msg.text = msg.text .. " The turn count is " .. count .. ".\r";
    	Comm.deliverChatMessage(msg);
    end
    After this you need to register your callback in the combat tracker package.

    Code:
    -- This function is to initialize variables
    function onInit()
    	-- Here is where we register the onTurnStartEvent. We can register many of these which is useful. It adds them to a list and iterates through them in the order they were added.
    	CombatManager.setCustomTurnStart(onTurnStartEvent);
    end
    There you have it. If you load up Fantasy Grounds, you should see your extension listed. I suggest creating a new campaign to test your extension in, so you don't mess up an existing campaign with bugs. Throw a few creatures into the combat tracker and change turns and see what the chat log says.

    Any questions or comments are welcome.
    Last edited by lokiare; March 31st, 2018 at 14:16. Reason: Edited to modernize.
    For support post in the House of Healing or email [email protected]
    Have a suggestion for a feature? Go here http://fg2app.idea.informer.com/

  2. #2

    Join Date
    Apr 2007
    Location
    Mississippi, USA
    Posts
    491
    A user verified this tutorial is still valid for the 5E rule set.

  3. #3
    Hey folks. Just an FYI, I followed this tutorial to the letter and FG gave me an error over the following code.

    Code:
    <includefile source="campaign/campaign_images.xml" />
    I assume that is because this file does not exist anywhere in the extension folder or sub-folders.

    I would suggest removing that line because the extension won't load.

    I would love to see how that example works. But it might not be appropriate here, especially for new coders. Just a thought.

  4. #4
    damned's Avatar
    Join Date
    Mar 2011
    Location
    Australia
    Posts
    18,878
    Blog Entries
    1
    The windows have changed significantly since 3.2.0 so this tutorial will need some updating....

    MoreCore - Generic Ruleset
    --- Projects ---
    Extensions | Tutorials | MoreCore | MoreCore Themes | Call of Cthulhu | Maelstrom | FG Con

  5. #5
    Heheh JUST as I start reading tutorials, I am noticing a lot different I was warned the Runequest one is "a bit old" - so, if someone is trying to learn enough to get a feel on how to start extentions or rulesets, what would you suggest they start looking at to get the skeletons of needed work?

    Like, look at these 2 stickied then check patch notes or beta forum for description of changes? etc?

  6. #6
    damned's Avatar
    Join Date
    Mar 2011
    Location
    Australia
    Posts
    18,878
    Blog Entries
    1
    Quote Originally Posted by Varsuuk View Post
    Heheh JUST as I start reading tutorials, I am noticing a lot different I was warned the Runequest one is "a bit old" - so, if someone is trying to learn enough to get a feel on how to start extentions or rulesets, what would you suggest they start looking at to get the skeletons of needed work?

    Like, look at these 2 stickied then check patch notes or beta forum for description of changes? etc?
    What are you wanting to do?

  7. #7
    Trenloe's Avatar
    Join Date
    May 2011
    Location
    Denver, Colorado, USA (for a bit)
    Posts
    23,623
    Quote Originally Posted by Varsuuk View Post
    what would you suggest they start looking at to get the skeletons of needed work?
    https://www.fantasygrounds.com/forum...oreRPG-ruleset

    If you're modifying BRP read the guide that is supplied in the <FG app data>\docs directory.

    FG Con 15 Fantasy Grounds Online RPG Convention - Nov. 8-10, 2019
    Register at www.fg-con.com for all the latest info.

    Private Messages: My inbox is forever filling up with PMs. Please don't send me PMs unless they are actually private/personal messages. General FG questions should be asked in the forums - don't be afraid, the FG community don't bite and you're giving everyone the chance to respond and learn!

  8. #8
    That's the problem. I just want to learn how to read through existing CoreRPG and then maybe 5e / C&C that I own to learn enough to probably start by creating a character sheet for something (up in air atm) and code functionality to it to see how it goes.

    I'm a curious guy who enjoys mucking with coding - I have vague ideas in where I might want to go once I get a minimal understanding but no precise questions. If I did, I'd be golden because between you and some other community devs here, I could have my every question answered.

    My problem is where to start, what to read either in forums/pdfs to guide me while I look at the xml and lua. I had originally thought to start from the developer wiki to look at the creating that simple Runequest example. I knew it was old but suspected it could at least show me a set of steps even if the referenced files/names were off. Probably still good for that, I will be reading it throughout the day while wait on extensive performance tests I'm running here at the office.

    After that, I figured try reading through all of the armory forums for posts by others either giving tutorials first then people asking questions next in the forums figuring to get info by inference.

    But yeah, If you were to be asked "I want to learn HOW to develop a ruleset, I am thinking of doing something like taking C&C and making one change of some sort to something character related that is big (I'll likely make up something silly like adding Comeliness and some other mechanic I can find that I have no interest in other than to force me to learn how to make changes.

    After that, I'd probably try to implement something based on Core as. parent ruleset. Even if whatever I pick is closer to 3.5 or C&c etc, I want to build it closer to from scratch. This is for me, for my intellectual exercise. If I find I have a knack, certainly I would then seriously consider selecting some system I know that I'd like to see implemented.

    But yeah, right now I am looking for an outline of how to approach and if lucky, any posts or tutorials that even if dates, would allow me to gain insights.

  9. #9
    Trenloe's Avatar
    Join Date
    May 2011
    Location
    Denver, Colorado, USA (for a bit)
    Posts
    23,623
    Quote Originally Posted by Varsuuk View Post
    My problem is where to start, what to read either in forums/pdfs to guide me while I look at the xml and lua.
    https://www.fantasygrounds.com/forum...oreRPG-ruleset

    FG Con 15 Fantasy Grounds Online RPG Convention - Nov. 8-10, 2019
    Register at www.fg-con.com for all the latest info.

    Private Messages: My inbox is forever filling up with PMs. Please don't send me PMs unless they are actually private/personal messages. General FG questions should be asked in the forums - don't be afraid, the FG community don't bite and you're giving everyone the chance to respond and learn!

  10. #10
    Quote Originally Posted by Trenloe View Post
    https://www.fantasygrounds.com/forum...oreRPG-ruleset

    If you're modifying BRP read the guide that is supplied in the <FG app data>\docs directory.

    Thank you Trenloe, another of the wizards for this sort of stuff

    I'm actually not at all knowledgeable regarding BRO. I don't own it or any pdf on it (closest are all my Chaosium Midkemia books and boxed Thieves World?)

    Only reason I listed Runewuest was because it was the pdf linked on the developer wiki in "developing ruleset" as a simplistic tutorial on how to take the D20 ruleset (didn't look, guess that's an old one you can dl) and starting to make the Runequest one or something. As I said, I just started it and saw that much was not matching.

Thread Information

Users Browsing this Thread

There are currently 1 users browsing this thread. (0 members and 1 guests)

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  

Log in

Log in