1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
# Creating a new class
This documentation will guide you through creating a new class for scripts, inside the game code.
## Creating source files
The best practice is for each class to have their own source file.
Let's call our class `ExampleObject`, derived from `SimpleEntity`. inside the `code/fgame`, create 2 source files:
- `exampleobject.h` for the header
- `exampleobject.cpp` for the source
## Preparing the header file
The header file will contain the class prototype and will use `CLASS_PROTOTYPE(classname)` to define the information about the class for scripts to use it.
Sample code for the class:
```cpp
#include "simpleentity.h"
class ExampleObject : public SimpleEntity {
CLASS_PROTOTYPE(ExampleObject);
public:
ExampleObject();
~ExampleObject();
};
```
## Declaring the class in the source file
The next step is to declare the class. The class declaration defines the information for the class, such as the parent class, the class name, the class id (which is an alternate name) and the list of events that the class supports.
```cpp
#include "exampleobject.h"
#include "g_main.h" // for printing
// The first argument is the parent (SimpleEntity)
// The second argument is the class name (ExampleObject)
// The this argument (can be NULL) is the alternate class name alias the class ID (info_exampleobject)
//
// The class can be spawned using "local.ent = spawn ExampleObject" or "local.ent = spawn info_exampleobject"
CLASS_DECLARATION(SimpleEntity, ExampleObject, "info_exampleobject")
{
// This line is mandatory and defines the end of the event response
{NULL, NULL}
};
// The class constructor
ExampleObject::ExampleObject()
{
gi.Printf("Hello, world!\n");
}
// The class destructor
ExampleObject::~ExampleObject()
{
gi.Printf("I'm being deleted!\n");
}
```
## Creating script commands for the class
Each class has a response list, containing a list of `Event` followed by the associated method for each.
This is the constructor for `Event`, inside `code/qcommon/listener.h`:
```cpp
/**
* @brief Construct a new Event object
*
* @param command The command name
* @param flags flags See event flags in listener.h. Default value is EV_DEFAULT
* @param formatspec Format specifier. Arguments are : 'e' (Entity) 'v' (Vector) 'i' (Integer) 'f' (Float) 's' (String) 'b' (Boolean). Upper case letter = optional
* @param argument_names Name of each argument separated by spaces.
* @param documentation The event description
* @param type For scripts, can be the following value:
* EV_NORMAL - Normal command (local.inst Command)
* EV_RETURN - Return as a function (local.result = local.inst ReturnCommand)
* EV_GETTER - Return as a variable (local.result = local.listener.some_getter)
* EV_SETTER - Set as a variable (local.inst.some_setter = "value")
*/
Event(const char *command, int flags, const char * formatspec, cons char *argument_names, const char *documentation, byte type = EV_NORMAL);
```
Let's tweak ExampleObject prototype inside `exampleobject.h` to add a test method.
```cpp
#include "simpleentity.h"
class ExampleObject : public SimpleEntity
{
CLASS_PROTOTYPE(ExampleObject);
public:
ExampleObject();
~ExampleObject();
// New test method
void TestMethod(Event *ev);
};
```
In `exampleobject.cpp`, instantiate a new `Event` and link it in the response list of the ExampleObject class:
```cpp
#include "exampleobject.h"
// Define an event EV_ExampleObject_TestMethod with the name "test_method", accepting 1 argument of type "integer"
Event EV_ExampleObject_TestMethod
(
"test_method",
EV_DEFAULT,
"i",
"num_to_print",
"This is a test method.",
EV_NORMAL
);
CLASS_DECLARATION(SimpleEntity, ExampleObject, "info_exampleobject")
{
// Link the event with the member method of the class
{&EV_ExampleObject_TestMethod, &ExampleObject::TestMethod},
{NULL, NULL}
};
// The class constructor
ExampleObject::ExampleObject()
{
gi.Printf("Hello, world!\n");
}
// The class destructor
ExampleObject::~ExampleObject()
{
gi.Printf("I'm being deleted!\n");
}
// The test method
void ExampleObject::TestMethod(Event *ev)
{
int value;
value = ev->GetInteger(1);
gi.Printf("TestMethod called! With value: %d\n", value);
}
```
### Testing the class
Time to test this class.
1. Create a folder `tests` inside the `main` folder of the game.
2. Create a file `test_exampleobject.scr` with the following content:
```cpp
main:
// Spawn an instance of the ExampleObject class.
// Should print: "Hello, world!"
local.ent = spawn ExampleObject
// Call the custom "test_method".
// Should print: "TestMethod called! With value: 3"
local.ent test_method 3
// delete it
// Should print: "I'm being deleted!"
local.ent delete
end
```
3. Start the game
4. In the main menu, open the console and type the following commands to enable cheats:
- `set cheats 1`
- `set thereisnomonkey 1`
5. Start a map: `set g_gametype 1;devmap dm/mohdm6`
6. In the console, type: `testthread tests/test_exampleobject.scr`
You should see some stuff being printed into console.
|
