Simple use of an .ini file.

Post your own tutorials, guides and demos.

Post » Sun Jul 26, 2009 9:48 am

I had a bit of a look around, and I couldn't find any topics specifically refering to .ini files and how they are structured and used. So, I figured I'd post up a little about what I've learned after tearing apart other peoples .caps. It's nothing spectacular, as I'm still learning a majority of stuff as well.

The first thing to know is how an .ini file is structured. They have 3 seperate parts; the group, the item, and the value.

An example of how an .ini file might look:

[code:2grvp9ic]
[Names]
Name1=Fred
Name2=Bob
Name3=Jack
Name4=Tom
[/code:2grvp9ic]

In that example, [Names] is the group; Name1, Name2, Name3 and Name4 are items; and Fred, Bob, Jack and Tom are values. Inside our .ini file, we can have as many groups and items as we need.

In Construct, before we can do anything with an .ini file, we need to add in the INI object. This object doesn't need to be placed in the layout, similar to the Mouse & Keyboard object.

Then we need to tell Construct to load the file. It's simple to do.

[code:2grvp9ic]System - Start of Layout
> INI Set INI file to AppPath + "names.ini"[/code:2grvp9ic]

Putting this as your first event will set the location of the .ini file you want to use. AppPath tells Construct that the .ini file is located in the same place as the .cap or .exe you are running. If you have your .ini file in a different location from your .cap or .exe, you need to specify its location instead of AppPath.

When we want to get a value from out of our .ini file, we need to specify which group and which item we want to get. In this example, if we wanted to get the name Jack, we need to specify the Names group, and the Name3 item.

Say we want to display the name Jack in a text object when an event is met, like your player sprite overlaps an something else. To do this, you would do something similar to:

[code:2grvp9ic]Player is overlapping JackTrigger
> Text set text to INI.ItemString("Names", "Name3")[/code:2grvp9ic]

Using an event similar to that should cause the name Jack to appear in the text object.

To explain what the condition means; obviously we are taking the Text object, and setting the text to something. We have specified that we want to set the text to what we find in our loaded .ini file. Inside the brackets, we tell Construct exactly which part of the .ini we want to display. "Names" is the name of the group we want to look in. Telling Construct to look there will cause it to ignore any other groups in the file during this condition. Then, we tell Construct to look at the item Name3. Now that we have specified the group and the item, Construct can now take the string contained in Name3, and display it in the Text object.

Worth noteing in relation to where we said INI.ItemString in the above event. When loading data from an .ini file, you can grab it in two different ways, with .ItemString or .ItemValue. If you are only storing text, or things you want to appear as text, then use .ItemString. However, if you are using an .ini file to load a value for something you need to use in any math, like a weapons power or a sprite location, you want to use .ItemValue. If you use ItemString when you want to load a number you want to manipulate later on, Construct will consider it as a text string, and you will be unable to use it in math operations and the like. On the other side, if you load text using .ItemValue, Construct will be unable to use it in math, and will default it to a value of 0. So, when loading data from an .ini file, make sure you use the right expression for the purpose you want to use that data for.

This is only a simple example of the use of an .ini file. Once you begin to explore and understand how to manipulate them, their uses increase dramatically. You can use an .ini file to store locations of sprites placed in a level editor for saving, or read them for loading them, or for various attributes for items in your RPG. A small RPG item list might look like this:

[code:2grvp9ic][Item1]
Name=Bronze Sword
Power=20
Weight=5
Cost=100
Description=A simple, uninteresting sword cast from bronze

[Item2]
Name=Holy Sword
Power=200
Weight=30
Cost=10000
Description=A sword of holy vengeance, once held by an angel[/code:2grvp9ic]

To make use of that data when loading, you would specify which one of the items you want to use (if you wanted to use the Holy Sword, you would specify Item2 as the group), and then you can load the data from the items Name, Power, Weight, Cost and Description. Use .ItemString for Name and Description (because the data inside is text, and we will only really use that data in a text object), and .ItemValue for Power, Weight and Cost (because we want the data to remain as values, so we can use them later in equations to determine how much damage the sword does, how much it costs to buy one, and so forth). How you would use that data is up to you to work out though, I'm only showing you how to get those values out of a .ini file.

I'm including a sample .cap so you can see the use of a .ini file in action. Again it's nothing special, but if you don't know how to use a .ini file, this should hopefully give you a rough idea of the things that you can do. Feel free to open up the .ini file to see how I've structured it. I've also commented the .cap, and I hope it's simple enough to understand my rambling in there.

Note: When extracting the .rar, keep the .cap and the .ini in the same folder as each other, otherwise the example won't work.

Using the .cap: The .cap produces 100 stars on the screen, and gives them all a name (set in two private variables). The names are randomly pulled from the .ini file. When you hover over one of the stars, the text object at the bottom of the screen will display the name of the star.

Construct Version: The example was made in the latest (0.99.42) version of Construct, so will not open in earlier versions, so you may need to update to be able to use it.

I hope my little explanation of using an .ini file and the .cap I've provided were easy enough to follow, and help some people out. Feel free to use the .cap in any way you wish; mess around with it, adapt it for your own projects, whatever you like.

https://files.getdropbox.com/u/1414019/starmap.rar
B
3
S
1
G
3
Posts: 14
Reputation: 1,053

Post » Sun Jul 26, 2009 10:40 am

This couldn't have come at a better time for me, thanks. I was planning to do something with hash tables, this is a much better solution and I had no idea what the INI files were for.

Thanks
B
2
S
2
G
3
Posts: 114
Reputation: 1,553

Post » Wed Jul 29, 2009 3:16 pm

Good tuto explains lots of things though no help to me as I know INI's very well already but nevertheless good one!

Thumbs up!
B
11
S
3
G
4
Posts: 622
Reputation: 3,186

Post » Thu Jul 30, 2009 1:14 am

Thanks Sagal, and MisfitBYTE, I'm glad it was helpful.

The best thing is that reading and writing values to a .ini can be a really powerful thing, and opens a massive world up to you. I only touched on the most basic of uses. If you go for a look back over the Uploads forum, you should be able to find quite a few other examples using an .ini file, like making a level editor, saving status, and many more.
B
3
S
1
G
3
Posts: 14
Reputation: 1,053

Post » Thu Jul 30, 2009 1:45 pm

Familiar with everything expect haven't tried save system :)
B
11
S
3
G
4
Posts: 622
Reputation: 3,186

Post » Thu Jul 30, 2009 9:29 pm

One good thing to remember about INI files: Reading/writing information means reading from/writing to the disk, which is notably slower than reading from/writing to memory.

I learned this the hard way with MMF2 when I was creating a SHMUP-style game that had all the enemy wave information saved in an INI file. Every time an enemy spawned the game lagged notably.

In the end, I made the engine load the wave information to an array at the start of the game and then reading all the information from this array during runtime. This solved the lag problem as the only reading from disk happened during the start.
B
16
S
8
G
4
Posts: 136
Reputation: 3,144

Post » Fri Jul 31, 2009 9:13 am

If you save INI file as a resource, I believe that it is fully loaded into memory as the project is loaded. But I don't know much about resources, so don't quote me on that.
B
62
S
21
G
12
Posts: 1,910
Reputation: 13,155

Post » Fri Jul 31, 2009 9:58 am

Well, it certainly reads the files on the fly if you don't set it as a resource, seeing as you can edit something in the .ini file while the game is running and it'll update in real-time (as in next time the value is called).

You could also test the resource thing this way, as if it's loaded to the memory it shouldn't update changes made to the file itself, unless it monitors the file for changes or something.

Some sort of INI caching would be nice though in order to avoid the slowness of reading from disk for things that won't really change during runtime.
B
16
S
8
G
4
Posts: 136
Reputation: 3,144

Post » Sat Nov 07, 2009 9:53 am

Very useful info, thanks! :)
Perfect for storing user preferences and such.
B
3
S
1
G
4
Posts: 42
Reputation: 1,609

Post » Tue Nov 10, 2009 9:31 am

Wow, been a long while since I was last here, caught up with study and other assorted thing, and certainly a surprise to see this little tid-bit floating about. Glad it's still of help to people. :D
B
3
S
1
G
3
Posts: 14
Reputation: 1,053

Next

Return to Your tutorials & example files

Who is online

Users browsing this forum: No registered users and 0 guests