| 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 |