Custom Pointers Coding Toolkit - Over Several Posts

[ShotGun Jolly]

I have been searching for a week, trying to find where that code goes. No luck.. anyone out there willing to assist me in finding where I need to insert the code to allow me to see that cone?

[dulux-oz]

I have been searching for a week, trying to find where that code goes. No luck.. anyone out there willing to assist me in finding where I need to insert the code to allow me to see that cone?

OK, to link everything together you need to put the following code into an imagecontrol:

<imagecontrol>
	<pointertypes>
		<custom name="45Cone">
			<icon>pointer_cone</icon>
			<label>Draw a 45-Degree Cone</label>
		</custom>
	</pointertypes>
</imagecontrol>

This is explained in the 2nd Post. The imagecontrol we (normally) use is the main one, located in the campaign_images.xml file in the CoreRPG Ruleset in the Campaign Folder (it starts at line 28). If you are using another Ruleset not derived from the CoreRPG Ruleset then the location of the file may be different - but that's where its gotta go.

We also need to tell the imagecontrol where the code for the onBuildCustomPointer() function (and the functions called by onBuildCustomPointer()) lives. The code to do this is (assuming the file containing these functions is called Pointer_Toolkit.lua):

<imagecontrol>
	<script file="Pointer_Toolkit.lua" />
</imagecontrol>

This is also explained in 2nd post.

But remember, the Pointers Toolkit is a Toolkit - not a complete set of files you can "drop in" to an existing Ruleset. If it was, it would be an Extension, not a Toolkit! In other words, treat it like a piece of furniture from Ikea - some assembly required.

Any other questions please ask.

Cheers

[dulux-oz]

Hi Guys,

Because I've been informed that some people are having trouble using the Pointer Toolkit I put together this post to try to make things clearer - Enjoy!

IMPORTNAT POINT No 1

Pointers can be considered an "advanced" topic in FG Coding. You NEED to FULLY read and understand the Pointer Toolkit Documentation to be able to use the Toolkit consistently and successfully. Just about all of the issues people have had with getting the Toolkit to work have stemmed from the fact that they HAVEN'T FULLY read and/or understood the documentation (and/or they've been trying to use the Toolkit to do things it wasn't designed to do).

IMPORTNAT POINT No 2

The Pointer Toolkit is NOT designed to be used "as is" - it's a Toolkit - you take the individual tool or tools from the kit and use them in your project.

IMPORTNAT POINT No 3

The Pointer Toolkit includes some SAMPLE or EXAMPLE functions to show you how to achieve certain results. If the Sample functions are useful to use "as is", by all means use them - BUT they were designed as Examples, not as finalised code.

OK, now that we've understood these three very important points, lets get started.

FG has two types of Pointers: Standard Pointers and Custom Pointers.

The Standard Pointers are: Circle, Square, 90-Degree Cone and Arrow. Custom Pointers are Pointers we create.

We don't need to do anything to the FG Code to use the Standard Pointers, UNLESS we want to use one or more Custom Pointers in our Ruleset.

Any Ruleset can have a MAXIMUM of 5 Pointers. The 5 Pointers can be a mix of Standard and Custom Pointers.

Any Pointer is made up of Lines, Curves and Quarter-Ellipse Curves.

To draw a Line we use the fpLineCurve() function from the Toolkit and give it the Starting and Ending X- and Y-Coordinates, plus an Offset. I'll explain what the Offset does later. Most people will use an Offset of 0.

To draw a curve we can use either the fpAngleArcCurve() or the fpEndpointArcCurve() function and give them the Starting X- and Y-Coordinates of the Curve, the X- and Y-Coordinates of the Centrepoint of the Circle the Curve is a part of and either the Angle that the Curve needs to cover in Degrees (for the first function) or the Ending X- and Y-Coordinates of the Curve (for the second function). Both of these functions in turn call the fpArcCurve() function.

To draw a Quarter-Ellipse curve we can use the fpEllipseCurve() function and give it the X- and Y-Radius of the Quarter-Ellipse, plus an Offset. The "flatness" of the Quarter-Ellipse depends upon the ratio of the two Radii: if they are the same (ie 1:1) we end up with a Quarter-Circle.

So, if your Pointer has Lines you need to include the fpLineCurve() function, if it has Quarter-Ellipses you need to include the fpEllipseCurve() function, and if it has Curves you need to include the fpArcCurve() function and either (or both) the fpAngleArcCurve() or the fpEndpointArcCurve() function, depending upon how you draw your curves (End-Point or Angle-of-Arc).

These five functions are called Curve Definition Functions.

OK, so How do we do this?

Well, Pointers are part of imagecontrols, so we need to modify the imagecontrol used to display maps, etc. In the CoreRPG this imagecontol is called "image" and is found starting at line 28 of the campaign/campaign_images.xml file. If we look at line 35 of this file we can see that the image imagecontrol calls a script file called image.lua in the campaign/scripts folder. So we know we need to modify these two files: we need to put the relevant functions from the Pointer Toolkit into the image.lua file and make some changes to the image imagecontrol in the campaign_images.xml file. Of course, this is just one way of accomplishing our goal - and we need to be aware that if we modify these two files the next time FG is updated the two files will be reverted back to they way they were before we changed them - some people solve this problem by putting their Custom Pointers in an Extension, but this can lead to conflicts with other Extensions that deal with the image imagecontrol.

To tell FG that we want to use Custom Pointers we need to put a <pointertypes> tag inside the image imagecontrol and a pointer tag for each Custom Pointer AND one for each Standard Pointer. The SAMPLE Code below shows a <pointertypes> tag with 5 pointer tags: one for each of the Standard Pointers and one for a Custom Pointer called "45Cone".

<imagecontrol>
	<pointertypes>
		<custom name="45Cone">
			<icon>pointer_cone</icon>
			<label>Draw a 45-Degree Cone</label>
		</custom>
		<arrow>
			<icon>pointer</icon>
			<label>Draw Arrow</label>
		</arrow>
		<square>
			<icon>pointer_square</icon>
			<label>Draw Square</label>
		</square>
		<circle>
			<icon>pointer_circle</icon>
			<label>Draw Circle</label>
		</circle>
		<cone>
			<icon>pointer_cone</icon>
			<label>Draw Cone</label>
		</cone>
	</pointertypes>
<!-- Other imagecontrol tags -->
</imagecontrol>

Once FG sees the <pointertypes> tag and the corresponding <custom> tag it automatically calls a function called onBuildCustomPointer() with takes the Starting and Ending X- and Y-Coordinates of the Pointer, plus a string representing the Custom Pointer name (eg "45Cone"). We don't have to worry about calling onBuildCustomPointer() with the correct values: FG takes care of this for us. We do have to tell onBuildCustomPointer() what to do, such as work out the length of the Pointer, etc, plus draw the Pointer. Obviously, onBuildCustomPointer() should go into the same file that we've placed the required Curve Definition Functions in (eg image.lua or our Extension).

The best way to draw a Pointer is have onBuildCustomPointer() call a Pointer-Drawing function, one for each Custom Pointer. These Pointer-Drawing functions also go into the file with the other functions (eg image.lua).

To draw a Pointer FG expects a table of Coordinates. The Curve Definition Functions return the correctly values in the correct format, so if our Pointer-Drawing function calls the correct Curve Definition Functions with the correct values, then we've drawn our Pointer.

The Pointer Toolkit includes 11 SAMPLE Pointer-Drawing functions and a SAMPLE onBuildCustomPointer() function to show you how to do this.

Pointers are drawn centred around the Start Point (for Circles, Squares, etc) or originating at the Start Point (for Cones and Arrows) and extending out to the End Point. Remember the Offset value used in some of the Curve Definition Functions? This causes the Line/Ellipse-Curve to "slide along" the line from the Start Point to the End Point. If you look closely at the Sample Pointer-Drawing functions you can see how this works.

So, to summarise: take the functions and Sample functions from the Toolkit and place them in a file. Link the file (if it isn't already) to the imagecontol. Tell FG to use the Custom Pointers via the <pointertypes> tag.

And have fun!

I hope this has made things clearer for everyone.

Any question, please ask.

Cheers

[Blackfoot]

I think you are assuming a lot to think we can actually understand the documentation.
Honestly.. I don't really understand half of what you type.

[dulux-oz]

I think you are assuming a lot to think we can actually understand the documentation.

OK, fair comment. I have assumed a basic level of knowledge, which (IMNSHO) is the minimum required if someone is going to be creating Extensions and Rulesets. However, you know what they say about assuming: it makes an @ss out of you and me. Everyone is different and everyone learns/understands things in a different way, so let's see what we can do to get this sorted.

Which part (of the doco) is causing you grief or where are you getting caught up?

[Trenloe]

FYI the square pointertype should be <rectangle>, square doesn't work. M_W confirmed that rectangle should be used.

Use the following for the 4 basic (default) types:

<imagecontrol>
	<pointertypes>
		<arrow>
			<icon>pointer</icon>
			<label>Draw Arrow</label>
		</arrow>
		<rectangle>
			<icon>pointer_square</icon>
			<label>Draw Square</label>
		</rectangle>
		<circle>
			<icon>pointer_circle</icon>
			<label>Draw Circle</label>
		</circle>
		<cone>
			<icon>pointer_cone</icon>
			<label>Draw Cone</label>
		</cone>
	</pointertypes>
</imagecontrol>

[ShotGun Jolly]

So, just so you know. After all the help I got with the 30* cone pointer. Which is greatly appreciated. I decided to keep working on it myself to figure out why I couldn't get the instructions to work. And then it struck me like a ton of bricks. The problem I had, where the end points would show, but not the outline. It was due to the same problem we solved in other post. I had alternate extensions that were effecting the code. Once I turned them off, I was able to draw what I needed.

So, I wanted to verify that the instructions in Dulux's thread here did work, and I was able to follow them. In fact, the whole time I was looking for help to solve why it didnt work, it actually was working.. it was just conflicting with another extension. Bone head move on my part. But I just wanted to let people know that the instructions here do work.

[dulux-oz]

So, just so you know. After all the help I got with the 30* cone pointer. Which is greatly appreciated. I decided to keep working on it myself to figure out why I couldn't get the instructions to work. And then it struck me like a ton of bricks. The problem I had, where the end points would show, but not the outline. It was due to the same problem we solved in other post. I had alternate extensions that were effecting the code. Once I turned them off, I was able to draw what I needed.

So, I wanted to verify that the instructions in Dulux's thread here did work, and I was able to follow them. In fact, the whole time I was looking for help to solve why it didnt work, it actually was working.. it was just conflicting with another extension. Bone head move on my part. But I just wanted to let people know that the instructions here do work.

Thankyou for that - it takes a lot of guts to publicly admit when you're wrong, and I for one appreciate you setting the record straight.

I'm glad you got things sorted - for my own edification, which was the other Extension(s)?

Cheers

[ShotGun Jolly]

I have no problem saying I made a mistake, even more so when I do not have a sweet fracking clue on how all of this works other then what I have read here on the forums.

Now that I am finally starting to understand the bare bones of it. Some things are starting to fall into place a little easier. Don't get me wrong, your instructions are great but they are well over my head when it comes to understanding them. It took me a long while of poking around to figure some of the stuff out. But, all the answers are there, I just needed to roll a few critical successes on my Cryptography skills to get there

As for your question, it was just one of my own Frankenstein copy/paste concoctions I had made when I first started to mess with this in the first place.

[damned]

it was just one of my own Frankenstein copy/paste concoctions I had made when I first started to mess with this in the first place.

Doh!
I mess up my code so bad sometimes...