33
edits
AGS Pointers for Dummies: Difference between revisions
Link to online manual
Monkey'05'06 (talk | contribs) No edit summary |
(Link to online manual) |
||
| Line 13: | Line 13: | ||
==Variables== | ==Variables== | ||
A variable, in the context of scripting, is a way to represent a value. In AGS, there are five different | A variable, in the context of scripting, is a way to represent a value. In AGS, there are five different [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm data types] which can be used to represent a variable. These types include '''char''', '''short''', '''int''', '''String'''{{footnote parent|1}}, and '''float'''. A '''char'''-type variable is one that can hold only a single character (i.e., 'A', 'B', etc.) or a number within the range 0 to 255. A '''short'''-type variable can store integers within the range -32768 to 32767. An '''int'''-type variable can store integer values within the range -2147483648 to 2147483647. A '''String'''-type variable can hold a string of characters (i.e., "this is some text!") of ''virtually''{{footnote parent|2}} infinite length. A '''float'''-type variable can store floating-point decimals within the range -2147483648.0 to 2147483647.0, and has precision{{footnote parent|3}} up to approximately 6 decimal places, though this will vary based on the actual number. | ||
For information on defining and assigning values to variables read the entry in the manual | For information on defining and assigning values to variables read the entry in the manual [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm data types]. | ||
==Pointers== | ==Pointers== | ||
| Line 26: | Line 26: | ||
==Managed Types== | ==Managed Types== | ||
AGS has certain ''managed'' types{{footnote alt parent|4}} that you can not create an instance (variable declaration) of, but you ''can'' create pointers to{{footnote parent|5}}. All of the variables of managed types are ''managed'' by AGS. These include the types: | AGS has certain ''managed'' types{{footnote alt parent|4}} that you can not create an instance (variable declaration) of, but you ''can'' create pointers to{{footnote parent|5}}. All of the variables of managed types are ''managed'' by AGS. These include the types: [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags45.htm AudioChannel], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags46.htm AudioClip], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags54.htm Button], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags47.htm Character], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags48.htm DateTime], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags49.htm Dialog], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags50.htm DialogOptionsRenderingInfo], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags51.htm DrawingSurface], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags52.htm DynamicSprite], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags53.htm File], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags54.htm Game], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags55.htm GUI], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags56.htm GUIControl], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags63.htm Hotspot], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags64.htm InventoryItem], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags58.htm InvWindow], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags59.htm Label], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags60.htm ListBox], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags65.htm Maths], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags66.htm Mouse], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags68.htm Object], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags69.htm Overlay], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags71.htm Parser], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags72.htm Region], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags73.htm Room], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags61.htm Slider], [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags62.htm TextBox], and [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags74.htm ViewFrame]. | ||
==Working With Managed Types== | ==Working With Managed Types== | ||
| Line 37: | Line 37: | ||
==Array of Pointers== | ==Array of Pointers== | ||
It should be noted here that when defining pointers, you can also create an | It should be noted here that when defining pointers, you can also create an [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm#Arrays array] of pointers. When you create an array you are simply defining a set of variables (or in this case, pointers) which all have the same name. You access each one individually using an index between brackets ([ and ]). | ||
Defining an array of pointers works the same way as defining any other array does, so to define an array of GUI*s called myguis to hold 5 GUI*s, you would type: | Defining an array of pointers works the same way as defining any other array does, so to define an array of GUI*s called myguis to hold 5 GUI*s, you would type: | ||
| Line 47: | Line 47: | ||
===Dynamic Array of Pointers=== | ===Dynamic Array of Pointers=== | ||
As of AGS 3.0, you can have | As of AGS 3.0, you can have [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags37.htm#DynamicArrays dynamic arrays] of the built-in types, including the managed types. The assignment here works a little differently: | ||
GUI *daguis[] = new GUI[5]; | GUI *daguis[] = new GUI[5]; | ||
| Line 108: | Line 108: | ||
The String type isn't one of AGS's managed types, nor can you create a pointer to it. So why then am I bringing it up? The fact is, the String type is actually internally defined as a pointer, which is how it is able to have it's virtually infinite maximum length. | The String type isn't one of AGS's managed types, nor can you create a pointer to it. So why then am I bringing it up? The fact is, the String type is actually internally defined as a pointer, which is how it is able to have it's virtually infinite maximum length. | ||
Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an | Prior to AGS 2.71, AGS used the now deprecated string type. The string type was internally defined as an [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm#Arrays array] of 200 characters ('''char'''s). This meant that strings had a maximum length of 200 characters themselves. | ||
With the introduction of AGS 2.71 came the new String type which removed that limit. And how did it do it? It used a pointer. Not an AGS-style pointer, but a pointer nonetheless. In programming languages such as C and C++, a pointer-to-char (char*){{footnote parent|7}} creates a special type of pointer. Instead of just pointing to one single variable, a char* can point to a virtually infinite number of chars in the form of what is known as a string-literal (such as "this is some text"). | With the introduction of AGS 2.71 came the new String type which removed that limit. And how did it do it? It used a pointer. Not an AGS-style pointer, but a pointer nonetheless. In programming languages such as C and C++, a pointer-to-char (char*){{footnote parent|7}} creates a special type of pointer. Instead of just pointing to one single variable, a char* can point to a virtually infinite number of chars in the form of what is known as a string-literal (such as "this is some text"). | ||
| Line 165: | Line 165: | ||
===File*=== | ===File*=== | ||
Another example can be seen if we look at the | Another example can be seen if we look at the [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags53.htm File] type. | ||
In an integral system, you would access an external file like this: | In an integral system, you would access an external file like this: | ||
| Line 217: | Line 217: | ||
==Extending The Built-In (Managed) Types== | ==Extending The Built-In (Managed) Types== | ||
Now that we've seen what pointers are, how they are used, how they relate to AGS, and some basic uses of them, let's take a look at a different kind of usage. In AGS we can create our own custom-defined datatypes using | Now that we've seen what pointers are, how they are used, how they relate to AGS, and some basic uses of them, let's take a look at a different kind of usage. In AGS we can create our own custom-defined datatypes using [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm#struct struct]. | ||
You define a struct like this: | You define a struct like this: | ||
| Line 262: | Line 262: | ||
==Dynamic Arrays Are Pointers Too== | ==Dynamic Arrays Are Pointers Too== | ||
In addition to the managed types, there are another type of pointer you should be aware of: | In addition to the managed types, there are another type of pointer you should be aware of: [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags37.htm#DynamicArrays dynamic arrays]. You can create a dynamic array of the base types (such as int) or of pointers to a managed type (such as Character*). For creating a dynamic array of pointers, see {{link||Dynamic Array of Pointers}}. | ||
Unlike the managed types, you use the '''new''' keyword to create a new array dynamically. The name you give it is treated as a pointer. The manual gives us this example: | Unlike the managed types, you use the '''new''' keyword to create a new array dynamically. The name you give it is treated as a pointer. The manual gives us this example: | ||
| Line 284: | Line 284: | ||
{{footnote text|2|The length for Strings is limited by your computer's physical memory. A String will take up 4 bytes of memory, plus 1 byte for each character it contains.}} | {{footnote text|2|The length for Strings is limited by your computer's physical memory. A String will take up 4 bytes of memory, plus 1 byte for each character it contains.}} | ||
{{footnote text|3|Floating-point decimals won't always evaluate as you might expect when doing certain mathematical operations (this is due to their precision levels). See the manual entry on | {{footnote text|3|Floating-point decimals won't always evaluate as you might expect when doing certain mathematical operations (this is due to their precision levels). See the manual entry on [https://www.adventuregamestudio.co.uk/manual/index.html?page=ags44.htm#DataTypes data types] for more information.}} | ||
{{footnote text|4|AGS's managed types are those listed here. You cannot create a new managed type within AGS's scripts; to create a new managed type you would need to write a plugin. Some module writers may use the keyword ''managed'' to prevent users from creating instances of structs that are meant to be used statically. This does not however make the type managed. Only AGS's built-in managed types and any managed types created via plugins are actually managed, and therefore are the only types that can have pointers to them.}} | {{footnote text|4|AGS's managed types are those listed here. You cannot create a new managed type within AGS's scripts; to create a new managed type you would need to write a plugin. Some module writers may use the keyword ''managed'' to prevent users from creating instances of structs that are meant to be used statically. This does not however make the type managed. Only AGS's built-in managed types and any managed types created via plugins are actually managed, and therefore are the only types that can have pointers to them.}} | ||