Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
entity.h
Go to the documentation of this file.
1/*
2** Jo Sega Saturn Engine
3** Copyright (c) 2012-2026, Johannes Fetz (johannesfetz@gmail.com)
4** All rights reserved.
5**
6** Redistribution and use in source and binary forms, with or without
7** modification, are permitted provided that the following conditions are met:
8** * Redistributions of source code must retain the above copyright
9** notice, this list of conditions and the following disclaimer.
10** * Redistributions in binary form must reproduce the above copyright
11** notice, this list of conditions and the following disclaimer in the
12** documentation and/or other materials provided with the distribution.
13** * Neither the name of the Johannes Fetz nor the
14** names of its contributors may be used to endorse or promote products
15** derived from this software without specific prior written permission.
16**
17** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19** WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20** DISCLAIMED. IN NO EVENT SHALL Johannes Fetz BE LIABLE FOR ANY
21** DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22** (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23** LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24** ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26** SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27*/
44
45#ifndef __JO_ENTITY_H__
46# define __JO_ENTITY_H__
47
48#if defined(JO_COMPILE_WITH_FS_SUPPORT) && defined(JO_COMPILE_WITH_3D_SUPPORT)
49
50# include "level.h"
51
53# define JO_ENTITY_MAX (1024)
55# define JO_ENTITY_MAX_CLASSES (24)
57# define JO_ENTITY_MAX_PENDING (32)
59# define JO_ENTITY_MAX_MODELS (32)
62# define JO_ENTITY_WAKE_DISTANCE (3000)
64# define JO_ENTITY_DRAW_DISTANCE (2000)
66# define JO_ENTITY_FAR_DISTANCE (600)
67
69# define JO_ENTITY_FLAG_DISABLED (0x0001)
72# define JO_ENTITY_FLAG_SOLID (0x0002)
73# define JO_ENTITY_FLAG_HIDDEN (0x0004)
75# define JO_ENTITY_FLAG_DEAD (0x0100)
76# define JO_ENTITY_FLAG_PLAYER_INSIDE (0x0200)
79# define JO_ENTITY_FLAG_DOORWAY (0x0400)
80
81typedef struct __jo_entity jo_entity;
82
84typedef struct
85{
86 const char *name; // Name in the level (ENTI.cls)
87 unsigned int data_size; // Bytes allocated for each entity (entity->data), 0: none
89 void (*spawn)(jo_entity * const entity);
93 void (*update)(jo_entity * const entity, const int elapsed);
97 bool (*action)(jo_entity * const entity, const int action, const int param, jo_entity * const source);
99 void (*death)(jo_entity * const entity, jo_entity * const source);
101 void (*draw)(jo_entity * const entity);
104 void (*draw_slave)(jo_entity * const entity);
107 void (*tint)(jo_entity * const entity, int * const r, int * const g, int * const b);
109
112{
113 // (the first 32 bytes: what the collisions read for each entity (jo_entities_is_blocked_at()), 2 lines of the cache)
114 unsigned int flags; // JO_ENTITY_FLAG_xxx
115 jo_pos3D_fixed position; // Foot (world space, Saturn Y down)
116 int radius; // Cylinder: collisions, bullets, zone of a trigger (world units)
118 short box_x; // Box turned with the entity (half sizes, world units) for the collisions
119 short box_z; // of the player and the entities (jo_entities_get_blocking()), 0: the cylinder
120 int yaw; // Degrees
122 const char *name;
123 int health; // 0: can't be damaged (or dead: JO_ENTITY_FLAG_DEAD)
124 jo_3d_mesh *mesh; // Model drawn (JO_NULL: none)
125 jo_3d_mesh *far_mesh; // Model drawn far away (JO_NULL: mesh)
126 jo_pos3D_fixed center; // Bounding sphere of the model (world space, at jo_entity_set_mesh())
128 int far_distance; // The far model is drawn farther (world units, on the ground)
129 int draw_distance; // The model is not drawn farther (world units, on the ground)
130 int timer; // Free for the class (milliseconds): the entity stays awake while > 0
131 int state; // Free for the class
132 void *data; // Data of the class (jo_entity_class.data_size)
133 unsigned short first_prop;
134 unsigned short prop_count;
135 unsigned short first_link;
136 unsigned short link_count;
137 // (internal) The cells of the entity for its depth bias (jo_entities_draw()): at its foot, then on the 4 sides of a
138 // door (-2: not found yet), found at this position in this generation of the cells (jo_cells_generation())
140 short cells[5];
141 unsigned short cell_generation;
142 // (internal) Prepared for the frame (see jo_entities_prepare_draw()): the distance of the view (see
143 // jo_entity_view_distance(), -1: not drawn), the tint (packed, see jo_3d_get_tint())
145 unsigned short tint;
146 // (internal) Height of the center of the bounding sphere above the position (the entity moves: its center follows)
148} __attribute__((aligned(16))); // (128 bytes: an entity of the table on 8 lines of the cache, see jo_entities_load())
149
156typedef void (*jo_entity_area_damage_callback)(const jo_pos3D_fixed * const center, const int radius,
157 const int damage, jo_entity * const source);
158
163
174void jo_entity_class_set_parallel_draw(const jo_entity_class * const cls, const bool parallel);
175
182int jo_entities_load(jo_level * const level);
183
186
191void jo_entities_update(const jo_pos3D_fixed * const player, const int elapsed);
192
201void jo_entities_set_wake(const int distance, const bool when_seen);
202
210void jo_entities_prepare_draw(const int slave_share);
211
219
225
230int jo_entities_test_counts(const int which);
231
237int jo_entities_polygon_count(const bool slave);
238
241
245jo_entity *jo_entity_get(const int index);
246
250jo_entity *jo_entity_find(const char * const name);
251
260void jo_entity_send(jo_entity * const target, const int action, const int param, jo_entity * const source);
261
267void jo_entity_fire(jo_entity * const source, const int event, const int param);
268
274void jo_entity_damage(jo_entity * const entity, const int damage, jo_entity * const source);
275
282void jo_entities_damage_area(const jo_pos3D_fixed * const center, const int radius, const int damage,
283 jo_entity * const source);
284
289
298jo_entity *jo_entities_ray_hit(const jo_pos3D_fixed * const origin, const jo_pos3D_fixed * const dir,
299 const jo_fixed max_t, jo_fixed * const t, jo_pos3D_fixed * const normal);
300
307bool jo_entities_is_blocked(const jo_fixed x, const jo_fixed z, const int radius);
308
319bool jo_entities_is_blocked_at(const jo_fixed x, const jo_fixed y, const jo_fixed z, const int radius,
320 const int height, const jo_entity * const except);
321
326void jo_entity_set_solid(jo_entity * const entity, const bool solid);
327
336 const jo_entity * const except);
337
344int jo_entity_get_int(const jo_entity * const entity, const char * const key, const int default_value);
345jo_fixed jo_entity_get_fixed(const jo_entity * const entity, const char * const key, const jo_fixed default_value);
346const char *jo_entity_get_string(const jo_entity * const entity, const char * const key,
347 const char * const default_value);
348
356bool jo_entities_get_zone_request(const char ** const level, const char ** const spawn);
357
360
365jo_3d_mesh *jo_entity_load_model(const char * const filename);
366
371jo_3d_model *jo_entity_get_model(const char * const filename);
372
378void jo_entity_set_mesh(jo_entity * const entity, jo_3d_mesh * const mesh);
379
385int jo_entity_view_distance(const jo_entity * const entity);
386
390void jo_entities_set_lod_scale(const int scale);
391
400int jo_entity_turn_to(jo_entity * const entity, const jo_fixed x, const jo_fixed z, const int max_step);
401
402/*
403** Actors: entities with an animated model (a skeleton, see jo_3d_model_draw_pose()). The class "actor" of the engine plays
404** the animation of its property animation (a character who waits, a flag); the classes of the game (enemies) start their
405** data with a jo_actor and call jo_actor_spawn(), jo_actor_update() and jo_actor_draw()
406*/
407
413typedef void (*jo_actor_bone_callback)(jo_entity * const entity, const int bone, const jo_fixed (* const matrix)[3]);
414
416typedef struct
417{
419 jo_3d_model *far_model; // (property far_model, the same bones and animations) JO_NULL: model
420 short animation; // Index in the model, -1: none
421 short previous; // Animation before the change (blended), -1: none
422 int time; // Milliseconds from the start of the animation
424 int blend; // Milliseconds left of the blend with the previous animation
427 int shadow_radius; // (property shadow) Its shadow on the ground (world units), 0: none
428} jo_actor;
429
434void jo_actor_spawn(jo_entity * const entity);
435
441void jo_actor_set_shadow(jo_entity * const entity, const int radius);
442
447void jo_actor_update(jo_entity * const entity, const int elapsed);
448
452void jo_actor_draw(jo_entity * const entity);
453
460void jo_actor_draw_slave(jo_entity * const entity, const int far_distance, const unsigned int hidden_bones);
461
468bool jo_actor_play(jo_entity * const entity, const char * const name, const int blend);
469
476bool jo_actor_restart(jo_entity * const entity, const char * const name, const int blend);
477
482bool jo_actor_is_done(const jo_entity * const entity);
483
489bool jo_actor_is_playing(const jo_entity * const entity, const char * const name);
490
491#endif /* !JO_COMPILE_WITH_FS_SUPPORT && JO_COMPILE_WITH_3D_SUPPORT */
492
493#endif /* !__JO_ENTITY_H__ */
494
495/*
496** END OF FILE
497*/
Mesh structure.
Definition 3d.h:248
int mesh_radius
Definition entity.h:127
bool jo_actor_is_done(const jo_entity *const entity)
Check if the animation of an actor is at its end (the last key of an animation that doesn't loop).
void(*) jo_entity_area_damage_callback(const jo_pos3D_fixed *const center, const int radius, const int damage, jo_entity *const source)
Damage around a point given to the game (the player is not an entity).
Definition entity.h:156
jo_3d_mesh * mesh
Definition entity.h:11
void jo_actor_draw_slave(jo_entity *const entity, const int far_distance, const unsigned int hidden_bones)
Draw an actor on the slave CPU (call it on the slave CPU, see jo_entities_draw_slave()): its model in...
int timer
Definition entity.h:130
int jo_entity_view_distance(const jo_entity *const entity)
Check if the model of an entity is drawn (near enough, in the view).
unsigned short first_link
Definition entity.h:135
jo_fixed center_dy
Definition entity.h:147
void jo_entity_damage(jo_entity *const entity, const int damage, jo_entity *const source)
Damage an entity: EVENT_DAMAGE, or the death (class death(), EVENT_DEATH) when its health reaches 0.
int health
Definition entity.h:123
int jo_entity_count(void)
Number of entities.
int shadow_radius
Definition entity.h:427
bool jo_entities_get_zone_request(const char **const level, const char **const spawn)
Change of level asked by an entity zone_link (the player went in it): the game fades the screen,...
void jo_actor_spawn(jo_entity *const entity)
Create the actor of an entity: its model (the model of the entity, it has a skeleton),...
int far_distance
Definition entity.h:128
bool jo_entities_is_blocked(const jo_fixed x, const jo_fixed z, const int radius)
Check if a circle on the ground is in a solid entity (collisions of the player).
jo_pos3D_fixed center
Definition entity.h:13
jo_pos3D_fixed position
Definition entity.h:115
short animation
Definition entity.h:420
void jo_entities_update(const jo_pos3D_fixed *const player, const int elapsed)
Update the entities: the delayed actions, the classes, the trigger zones.
jo_entity * jo_entities_ray_hit(const jo_pos3D_fixed *const origin, const jo_pos3D_fixed *const dir, const jo_fixed max_t, jo_fixed *const t, jo_pos3D_fixed *const normal)
First solid entity hit by a ray (its cylinder).
int radius
Definition entity.h:116
int radius
Definition entity.h:3
void(*) jo_actor_bone_callback(jo_entity *const entity, const int bone, const jo_fixed(*const matrix)[3])
Called when an actor is drawn, after each bone (a weapon in a hand, a muzzle flash).
Definition entity.h:413
int jo_entities_load(jo_level *const level)
Create the entities of a level (sections ENTI, PROP, LINK): the previous ones are freed.
bool jo_actor_is_playing(const jo_entity *const entity, const char *const name)
Check which animation an actor plays.
int state
Definition entity.h:131
jo_3d_model * model
Definition entity.h:418
jo_fixed jo_entity_get_fixed(const jo_entity *const entity, const char *const key, const jo_fixed default_value)
int blend_duration
Definition entity.h:425
bool jo_actor_restart(jo_entity *const entity, const char *const name, const int blend)
Play an animation again from its start.
void jo_actor_draw(jo_entity *const entity)
Draw an actor (its model in the pose of its animation) at its position, turned by its yaw.
void jo_actor_set_shadow(jo_entity *const entity, const int radius)
The shadow of an actor on the ground: a dark disc under its position (its feet), drawn with its model...
jo_entity * jo_entity_find(const char *const name)
Find an entity by its name.
unsigned short first_prop
Definition entity.h:133
const char * name
Definition entity.h:122
int blend
Definition entity.h:424
short box_z
Definition entity.h:119
short cells[5]
Definition entity.h:140
const jo_entity_class * cls
Definition entity.h:8
typedef __attribute__
16 bits word of any memory (see __jo_uint32_alias)
Definition types.h:50
unsigned short link_count
Definition entity.h:136
void jo_entity_class_set_parallel_draw(const jo_entity_class *const cls, const bool parallel)
Let the master CPU draw the entities of a class (its draw callback) while the slave CPU draws others ...
int jo_entities_draw(void)
Draw the entities of the master CPU (the camera matrix is the current matrix, see jo_3d_set_depth_bia...
void jo_entity_register_class(const jo_entity_class *const cls)
Register a class of the game (before jo_entities_load()).
short box_x
Definition entity.h:118
int jo_entities_slave_wait_time(void)
Time the master CPU waited for the entities of the slave CPU in the last frame (see jo_entities_draw(...
jo_3d_mesh * jo_entity_load_model(const char *const filename)
Load a model for the entities (loaded once: shared by all the entities).
int yaw
Definition entity.h:120
void jo_entities_prepare_draw(const int slave_share)
Prepare the drawing of the entities of the frame (the camera matrix is the current matrix,...
int height
Definition entity.h:117
int jo_entities_test_counts(const int which)
void jo_entity_set_mesh(jo_entity *const entity, jo_3d_mesh *const mesh)
Change the model of an entity (the dead model of an explosive...).
const char * name
Definition entity.h:9
short previous
Definition entity.h:421
jo_3d_model * jo_entity_get_model(const char *const filename)
Load a model for the entities (loaded once: shared by all the entities).
jo_actor_bone_callback bone_callback
Definition entity.h:426
void * data
Definition entity.h:132
int jo_entities_polygon_count(const bool slave)
Polygons of the entities of a CPU in the frame (see jo_entities_prepare_draw(): the polygons of their...
unsigned short prop_count
Definition entity.h:134
void jo_actor_update(jo_entity *const entity, const int elapsed)
Advance the animation of an actor.
void jo_entities_set_area_damage_callback(const jo_entity_area_damage_callback callback)
Give the damage around a point to the game (the player).
jo_3d_mesh * mesh
Definition entity.h:124
int far_distance
Definition entity.h:15
const jo_entity_class * cls
Definition entity.h:121
short view_distance
Definition entity.h:144
void jo_entities_set_lod_scale(const int scale)
A magnified view (binoculars, a sniper scope): the entities are drawn and detailed as far as they loo...
void jo_entities_clear_zone_request(void)
The change of level is done (see jo_entities_get_zone_request()).
void jo_entities_free(void)
Free the entities (and their models).
jo_3d_model * far_model
Definition entity.h:419
jo_entity * jo_entities_get_blocking(const jo_fixed x, const jo_fixed z, const int radius, const jo_entity *const except)
The solid entity in a circle on the ground (collisions of a vehicle).
jo_pos3D_fixed cell_position
Definition entity.h:139
int previous_time
Definition entity.h:423
const char * jo_entity_get_string(const jo_entity *const entity, const char *const key, const char *const default_value)
void jo_entity_send(jo_entity *const target, const int action, const int param, jo_entity *const source)
Send an action to an entity now.
void jo_entity_fire(jo_entity *const source, const int event, const int param)
Fire an event of an entity: its links send their actions (now or after their delay).
void jo_entities_damage_area(const jo_pos3D_fixed *const center, const int radius, const int damage, jo_entity *const source)
Damage everything around a point: the entities (their foot) and the game (see jo_entities_set_area_da...
int jo_entity_turn_to(jo_entity *const entity, const jo_fixed x, const jo_fixed z, const int max_step)
Turn an entity toward a point on the ground (its model looks toward +Z turned by its yaw: the directi...
bool jo_actor_play(jo_entity *const entity, const char *const name, const int blend)
Play an animation (nothing if it is already played).
bool jo_entities_is_blocked_at(const jo_fixed x, const jo_fixed y, const jo_fixed z, const int radius, const int height, const jo_entity *const except)
Like jo_entities_is_blocked(), with the heights: a solid entity blocks only a body at its level (a lo...
jo_3d_mesh * far_mesh
Definition entity.h:125
jo_entity * jo_entity_get(const int index)
An entity.
int jo_entities_draw_slave(void)
Draw the entities of the slave CPU (call it on the slave CPU, in the job between jo_3d_slave_begin() ...
int time
Definition entity.h:422
int height
Definition entity.h:4
void jo_entity_set_solid(jo_entity *const entity, const bool solid)
Make an entity solid or not (see JO_ENTITY_FLAG_SOLID).
jo_pos3D_fixed center
Definition entity.h:126
unsigned int flags
Definition entity.h:114
unsigned short tint
Definition entity.h:145
struct __jo_entity jo_entity
Definition entity.h:81
int jo_entity_get_int(const jo_entity *const entity, const char *const key, const int default_value)
Property of an entity (PROP).
unsigned short cell_generation
Definition entity.h:141
int draw_distance
Definition entity.h:129
void jo_entities_set_wake(const int distance, const bool when_seen)
The entities updated by jo_entities_update(): the ones that wait for something (timer > 0),...
An entity.
Definition entity.h:112
Data of an actor (the first member of the data of a class of actors).
Definition entity.h:417
Levels (.JOL files): the data of a level of a game (terrain, models, plants, decals....
A loaded level.
Definition level.h:51
3D model loaded from a JOM file
Definition model.h:242
Class of entities: its callbacks (JO_NULL: nothing to do).
Definition entity.h:85
void(*) tint(jo_entity *const entity, int *const r, int *const g, int *const b)
The tint of the entity (the light of the lamps on it, see jo_3d_point_lights_sample()) before it is d...
Definition entity.h:107
void(*) update(jo_entity *const entity, const int elapsed)
Each frame of the game, while the entity is awake (near the player or entity->timer > 0).
Definition entity.h:93
void(*) draw(jo_entity *const entity)
Draw the entity (the camera matrix is the current matrix), JO_NULL: its model at its position.
Definition entity.h:101
unsigned int data_size
Definition entity.h:87
const char * name
Definition entity.h:86
void(*) death(jo_entity *const entity, jo_entity *const source)
The health reached 0 (before the event DEATH).
Definition entity.h:99
void(*) draw_slave(jo_entity *const entity)
Draw the entity on the slave CPU (see jo_entities_draw_slave(): the slave 3D calls,...
Definition entity.h:104
bool(*) action(jo_entity *const entity, const int action, const int param, jo_entity *const source)
An action is received.
Definition entity.h:97
void(*) spawn(jo_entity *const entity)
The entity is created (its properties can be read).
Definition entity.h:89
int jo_fixed
Fixed point Q16.16 number.
Definition types.h:59
3D position using fixed numbers
Definition types.h:103