Debian Codegraph @

CorsixTH/Lua/entity.lua

raw
1 --[[ Copyright (c) 2009 Peter "Corsix" Cawley
2
3 Permission is hereby granted, free of charge, to any person obtaining a copy of
4 this software and associated documentation files (the "Software"), to deal in
5 the Software without restriction, including without limitation the rights to
6 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
7 of the Software, and to permit persons to whom the Software is furnished to do
8 so, subject to the following conditions:
9
10 The above copyright notice and this permission notice shall be included in all
11 copies or substantial portions of the Software.
12
13 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19 SOFTWARE. --]]
20
21 --! Abstraction for visible gameplay things which sit somewhere on the map.
22 class "Entity"
23
24 ---@type Entity
25 local Entity = _G["Entity"]
26
27 local TH = require("TH")
28
29 function Entity:Entity(animation)
30 -- World of the entity, set by World:newEntity()
31 self.world = nil
32
33 -- Index of the marker to use for displaying moods of the entity,
34 -- set by World:newEntity()
35 self.mood_marker = nil
36
37 self.th = animation
38 self.layers = {}
39 animation:setHitTestResult(self)
40 self.ticks = true
41 self.playing_sounds_in_random_sequence = false
42 self.waiting_for_sound_effects_to_be_turned_on = false
43 self.random_sound_sequence_parameters = nil
44 self.dynamic_info = nil
45 end
46
47 --[[
48 This plays a sound "at" the entity, meaning the sound will not be played
49 if the entity is off-screen, and the volume will be quieter the further
50 the entity is from the center of the screen. If this is not what you want
51 then use UI:playSound instead.
52 !param name (string, integer) The filename or ordinal of the sound to play.
53 !param played_callback (function) a optional parameter.
54 !param played_callback_delay (integer) a optional milliseconds parameter.
55 --]]
56 function Entity:playSound(name, played_callback, played_callback_delay)
57 if TheApp.config.play_sounds then
58 TheApp.audio:playSound(name, self, false, played_callback, played_callback_delay)
59 end
60 end
61
62 function Entity:setWaitingForSoundEffectsToBeTurnedOn()
63 self.waiting_for_sound_effects_to_be_turned_on = true
64 end
65
66 --[[
67 Plays a sequence of related sounds at an entity while entity.playing_sounds_in_random_sequence = true.
68
69 The silences between these sounds can either have randomly generated lengths between the min and max length parameters or
70 they can all be a specified length by providing min and max tables with one value for the desired pause duration.
71
72 !param name_pattern (String) example: LAVA00*.WAV
73 !param min_silence_lengths (table) the desired minimum silences length for the different tick rates, [3] = Normal
74 !param max_silence_lengths (table) the desired maximum silences length for the different tick rates, [3] = Normal
75 !param num_silences (integer) how many different silence lengths should be used, this can be a nil parameter.
76 -]]
77 function Entity:playEntitySounds(name_pattern, min_silence_lengths, max_silence_lengths, num_silences)
78 self.playing_sounds_in_random_sequence = true
79 self.random_sound_sequence_parameters = {}
80 self.random_sound_sequence_parameters["namePattern"] = name_pattern
81 self.random_sound_sequence_parameters["minSilence"] = min_silence_lengths
82 self.random_sound_sequence_parameters["maxSilence"] = max_silence_lengths
83 self.random_sound_sequence_parameters["numSilences"] = num_silences
84
85 TheApp.audio:playEntitySounds(name_pattern, self,
86 min_silence_lengths, max_silence_lengths, num_silences)
87 end
88
89 --[[ Set which animation is used to give the entity a visual appearance.
90 ! Until an entity is given an animation, it is invisible to the player. Note
91 that some "animations" consist of a single frame, and hence the term animation
92 is used both to mean things which are animated and things which are static.
93
94 !param animation (integer) The ordinal into the main animation set
95 !param flags (integer) A combination of zero or more drawing flags to control
96 the use of alternative palettes, transparency, and other similar settings. See
97 `THDF_` values in `th_gfx.h` for the possible bit values.
98 ]]
99 function Entity:setAnimation(animation, flags)
100 flags = flags or 0
101 if self.permanent_flags then
102 flags = flags + self.permanent_flags
103 end
104 if animation ~= self.animation_idx or flags ~= self.animation_flags then
105 self.animation_idx = animation
106 self.animation_flags = flags
107 self.th:setAnimation(self.world.anims, animation, flags)
108 end
109 return self
110 end
111
112 --[[ Set the map tile which the entity is on.
113 !param x (integer) The 1-based X coordinate of the tile.
114 !param y (integer) The 1-based Y coordinate of the tile.
115 ]]
116 function Entity:setTile(x, y)
117 if self.user_of then
118 print("Warning: Entity tile changed while marked as using an object")
119 end
120 local entity_map = self.world.entity_map
121 -- Remove the reference to the entity at it's previous coordinates
122 if entity_map then
123 entity_map:removeEntity(self.tile_x,self.tile_y, self)
124 end
125
126 self.tile_x = x
127 self.tile_y = y
128 -- NB: map can be nil, in which case th:setTile expects all nil arguments
129 self.th:setTile(x and self.world.map.th, x, y, self:getDrawingLayer())
130 if self.mood_info then
131 self.mood_info:setParent(self.th, self.mood_marker or 1)
132 end
133
134 -- Update the entity map for the new position
135 if entity_map then
136 entity_map:addEntity(x,y,self)
137 end
138
139 return self
140 end
141
142 function Entity:getRoom()
143 if self.tile_x and self.tile_y then
144 return self.world:getRoom(self.tile_x, self.tile_y)
145 else
146 return nil
147 end
148 end
149
150 --[[ Set the pixel position of the entity within the current tile.
151 !param x (integer) The 0-based X pixel offset from the default position.
152 !param y (integer) The 0-based Y pixel offset from the default position.
153 ]]
154 function Entity:setPosition(x, y)
155 self.th:setPosition(x, y)
156 return self
157 end
158
159 --[[ Set the rate at which the entity pixel position changes
160 !param x (integer) The X component of the speed in pixels per tick.
161 !param y (integer) The Y component of the speed in pixels per tick.
162 ]]
163 function Entity:setSpeed(x, y)
164 self.th:setSpeed(x, y)
165 return self
166 end
167
168 --[[ Combined form of `setTile`, `setPosition`, and `setSpeed`
169 !param tx (integer) The 1-based X coordinate of the tile.
170 !param ty (integer) The 1-based Y coordinate of the tile.
171 !param px (integer) The 0-based X pixel offset from the default position.
172 !param py (integer) The 0-based Y pixel offset from the default position.
173 !param sx (integer) The X component of the speed in pixels per tick.
174 !param sy (integer) The Y component of the speed in pixels per tick.
175 ]]
176 function Entity:setTilePositionSpeed(tx, ty, px, py, sx, sy)
177 self:setTile(tx, ty)
178 self:setPosition(px or 0, py or 0)
179 self:setSpeed(sx or 0, sy or 0)
180 return self
181 end
182
183 -- Inner tick function that will skip every other tick when
184 -- slow_animation is set.
185 function Entity:_tick()
186 if self.slow_animation then
187 if not self.skip_next_tick then
188 self.th:tick()
189 end
190 self.skip_next_tick = not self.skip_next_tick
191 else
192 self.th:tick()
193 end
194 end
195
196 -- Function which is called once every tick, where a tick is the smallest unit
197 -- of time in the game engine. Typically used to advance animations and similar
198 -- recurring or long-duration tasks.
199 function Entity:tick()
200 if self.num_animation_ticks then
201 for _ = 1, self.num_animation_ticks do
202 self:_tick()
203 end
204 if self.num_animation_ticks == 1 then
205 self.num_animation_ticks = nil
206 end
207 else
208 self:_tick()
209 end
210 -- Tick any mood animation
211 if self.mood_info then
212 self.mood_info:tick()
213 end
214
215 local timer = self.timer_time
216 if timer then
217 timer = timer - 1
218 if timer == 0 then
219 self.timer_time = nil
220 local timer_function = self.timer_function
221 self.timer_function = nil
222 timer_function(self)
223 else
224 self.timer_time = timer
225 end
226 end
227 end
228
229 --[[ Set which parts of the animation to be displayed.
230 ! Each animation is made up of 13 layers, and generally has several different
231 options for each layer. In the animation viewer tool, multiple options can be
232 toggled on for each layer, however here only one option may be selected per
233 layer.
234 !param layer (integer) The layer to set (1 through 13).
235 !param id (integer) The option to display for the given layer.
236 ]]
237 function Entity:setLayer(layer, id)
238 self.th:setLayer(layer, id)
239 self.layers[layer] = id
240 return self
241 end
242
243 --[[ Register a function (related to the entity) to be called at a later time.
244 ! Each `Entity` can have a single timer associated with it, and due to this
245 limit of one, it is almost always the case that the currently active humanoid
246 action is the only thing which calls `setTimer`.
247 If self.slow_animation is set then all timers will be doubled as animation
248 length will be doubled.
249 !param tick_count (integer) If 0, then `f` will be called during the entity's
250 next `tick`. If 1, then `f` will be called one tick after that, and so on.
251 !param f (function) Function which takes a single argument (the entity).
252 ]]
253 function Entity:setTimer(tick_count, f)
254 self.timer_time = tick_count
255 self.timer_function = f
256 if self.slow_animation and tick_count then
257 self.skip_next_tick = true
258 self.timer_time = tick_count * 2
259 end
260 end
261
262 -- Used to set a mood icon over the entity.
263 function Entity:setMoodInfo(new_mood)
264 if new_mood then
265 if not self.mood_info then
266 self.mood_info = TH.animation()
267 self.mood_info:setPosition(-1, -96)
268 self.mood_info:setParent(self.th, self.mood_marker or 1)
269 end
270 self.mood_info:setAnimation(self.world.anims, new_mood.icon)
271 else
272 if self.mood_info then
273 self.mood_info:setTile(nil)
274 end
275 self.mood_info = false
276 end
277 end
278
279 -- Function which is called when the entity is to be permanently removed from
280 -- the world.
281 function Entity:onDestroy()
282 -- Clear any mood
283 self:setMoodInfo()
284 self:setTile(nil)
285 self:onPickUp()
286 if self.waiting_for_sound_effects_to_be_turned_on then
287 TheApp.audio:entityNoLongerWaitingForSoundsToBeTurnedOn(self)
288 end
289 end
290
291 -- Function which is called when entity is picked up
292 function Entity:onPickUp()
293 self.world.dispatcher:dropFromQueue(self)
294 end
295
296 -- Function which is called at the end of each ingame day. Should be used to
297 -- implement behaviours which happen regularly, but not as frequently as to
298 -- need them in `tick`.
299 function Entity:tickDay()
300 end
301
302 --! Notify the entity of a new object.
303 --!param id Name of the new object.
304 -- TODO Currently only used for benches placed nearby.
305 -- TODO Maybe also pass the object tile coordinates?
306 function Entity:notifyNewObject(id)
307 end
308
309 --! Notify the entity that a new room was built.
310 --!param room (Room) The new room.
311 function Entity:notifyNewRoom(room)
312 end
313
314 function Entity:setMood(mood_name, activate)
315 end
316
317 -- Returns a table of hover info about an object.
318 function Entity:getDynamicInfo()
319 return self.dynamic_info
320 end
321
322 -- Sets a piece of Dynamic_info.
323 -- type could be 'text', 'progress' or 'dividers'
324 function Entity:setDynamicInfo(type, value)
325 if not self.dynamic_info then
326 self.dynamic_info = {
327 text = nil,
328 progress = nil,
329 dividers = nil,
330 }
331 end
332 self.dynamic_info[type] = value
333 end
334
335 -- Completely clears the dynamic info.
336 function Entity:clearDynamicInfo()
337 self.dynamic_info = nil
338 end
339
340 --! Stub to be extended in subclasses, if needed.
341 function Entity:afterLoad(old, new)
342 end
343
344 function Entity:playAfterLoadSound()
345 if self.random_sound_sequence_parameters then
346 self.playing_sounds_in_random_sequence = true
347 self:playEntitySounds(self.random_sound_sequence_parameters["namePattern"],
348 self.random_sound_sequence_parameters["minSilence"],
349 self.random_sound_sequence_parameters["maxSilence"],
350 self.random_sound_sequence_parameters["numSilences"])
351 end
352 end
353
354 --! Stub to be extended in subclasses, if needed.
355 function Entity:eraseObject()
356 -- Give entity the chance to clear itself from the map before resetAnimation gets called.
357 end
358
359 function Entity:resetAnimation()
360 local x, y = self.tile_x, self.tile_y
361 self.th:setTile(x and self.world.map.th, x, y, self:getDrawingLayer())
362 end
363
364 --[[
365 Returns the drawing layer for this particular entity. Should be overridden in derived classes. The drawing layer
366 specifies the order in which object are drawn in a tile (the object with the smallest layer is drawn first).
367 Litter should have layer 0, side objects to the north layer 1, side objects to the west layer 2,
368 normal objects should have layers between 3 and 7, east side object should have layer 8 and south side
369 objects layer 9.
370 ]]
371 function Entity:getDrawingLayer()
372 return DrawingLayers.Entity
373 end