-
Notifications
You must be signed in to change notification settings - Fork 9
/
ecs.lua
1277 lines (1100 loc) · 28.7 KB
/
ecs.lua
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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---@diagnostic disable: missing-return
--EmmyLua annotations and documentation for flecs-lua
--NOTE: ecs is a native module, this is not used at runtime.
local ecs = {}
---@class ecs_type_t
local ecs_type_t = {}
---@class ecs_ref_t
local ecs_ref_t = {}
---@class ecs_term_id_t
---@field id integer
---@field trav integer
---@field flags integer
local ecs_term_id_t = {}
---@class ecs_term_t
---@field id integer
---@field inout integer
---@field src ecs_term_id_t
---@field first ecs_term_id_t
---@field second ecs_term_id_t
---@field oper integer
local ecs_term_t = {}
---@class ecs_filter_t
---@field terms ecs_term_t|ecs_term_t[]
---@field expr string
local ecs_filter_t = {}
---@class ecs_query_t
local ecs_query_t = {}
---@class ecs_snapshot_t
local ecs_snapshot_t = {}
---@class ecs_iter_t
---@field count integer
---@field system integer
---@field event integer
---@field event_id integer
---@field self integer
---@field columns table[]
---@field entities integer[]
---@field table_count integer
---@field delta_time number
---@field delta_system_time number
---@field interrupted_by integer
---@field term_index integer
local ecs_iter_t = {}
---Create a new entity
---@overload fun()
---@overload fun(name: string)
---@overload fun(name: string, components: string)
---@overload fun(entity: integer)
---@overload fun(entity: integer, name: string)
---@param entity integer
---@param name string
---@param components string
---@return integer @entity
function ecs.new(entity, name, components)
end
--trailing arguments can be ommitted
ecs.new()
ecs.new(123)
ecs.new(123, "name")
--entity id can be ommited
ecs.new("name")
ecs.new("name", "component")
ecs.new(0, "name", "component1, component2")
--name can be nil
ecs.new(nil, "just_component")
ecs.new(123, nil, "component1, component2")
--the last argument cannot be nil
ecs.new(nil) --invalid
ecs.new(123, nil) --invalid
ecs.new(123, "name", nil) --invalid
ecs.new(123, 0, "component") --invalid: name must be a string or nil
---Create a new entity id without scope
---@return integer
function ecs.new_id()
end
---Delete an entity and all of its components
---@overload fun(entities: integer[])
---@param entity integer
function ecs.delete(entity)
end
---Create a tag
---@param name string
---@return integer @entity
function ecs.tag(name)
end
---Get the name of an entity
---@param entity integer
---@return string|nil @entity name
function ecs.name(entity)
end
---Set the name of an entity
---@param entity integer
---@param name string
---@return integer @entity id
function ecs.set_name(entity, name)
end
---Get the symbol name of an entity
---@param entity integer
---@return string|nil @entity symbol name
function ecs.symbol(entity)
end
---Get the full path for an entity
---@param entity integer
---@return string|nil
function ecs.fullpath(entity)
end
---Look up an entity by name
---@param name string
---@return integer
function ecs.lookup(name)
end
---Look up a child entity by name
---@param entity integer
---@param name string
---@return integer
function ecs.lookup_child(entity, name)
end
---Lookup an entity from a path
---@overload fun(parent: integer, path: string)
---@param parent integer
---@param path string
---@param sep string @optional
---@param prefix string @optional
---@return integer
function ecs.lookup_path(parent, path, sep, prefix)
end
---Lookup an entity from a full path
---@param name string
---@return integer
function ecs.lookup_fullpath(name)
end
---Look up an entity by its symbol name
---@param name string
---@return integer
function ecs.lookup_symbol(name)
end
---Add alias for entity to global scope
---@param entity integer
---@param name string
function ecs.use(entity, name)
end
---Test if an entity has a component, type or tag
---@overload fun(subject: integer, relation: integer, object: integer)
---@param entity integer
---@param to_check integer
---@return boolean
function ecs.has(entity, to_check)
end
---Test if an entity owns a component
---@param entity integer
---@param component integer
---@return boolean
function ecs.owns(entity, component)
end
---Test whether an entity is alive
---@param entity integer
---@return boolean
function ecs.is_alive(entity)
end
---Test whether an entity is valid
---@param entity integer
---@return boolean
function ecs.is_valid(entity)
end
---Get alive identifier
---@param entity integer
---@return integer
function ecs.get_alive(entity)
end
---Ensure id is alive
---@param entity integer
function ecs.ensure(entity)
end
---Test whether an entity exists
---Similar to ecs.is_alive, but ignores entity generation count
---@param entity integer
---@return boolean
function ecs.exists(entity)
end
---Add a component, type or tag to an entity
---@overload fun(subject: integer, relation: integer, object: integer)
---@param entity integer
---@param to_add integer
function ecs.add(entity, to_add)
end
---Remove a component, type or tag from an entity
---@overload fun(subject: integer, relation: integer, object: integer)
---@param entity integer
---@param to_remove integer
function ecs.remove(entity, to_remove)
end
---Clear all components
---@param entity integer
function ecs.clear(entity)
end
---Enable an entity or entity's component,
---depending on the number of arguments
---@overload fun(entity: integer)
---@param entity integer
---@param component integer
function ecs.enable(entity, component)
end
---Disable an entity or entity's component,
---depending on the number of arguments
---@overload fun(entity: integer)
---@param entity integer
---@param component integer
function ecs.disable(entity, component)
end
---Count entities that have a component or tag
---@param entity integer
---@return integer
function ecs.count(entity)
end
---Delete children of an entity
---@param parent integer
function ecs.delete_children(parent)
end
---Get the type of an entity
---@param entity integer
---@param from_entity boolean @return a type containing entity
---@return ecs_type_t|nil
function ecs.get_type(entity, from_entity)
end
---Get the typeid of an entity
---@param entity integer
---@return integer
function ecs.get_typeid(entity)
end
---Get parent for entity
---@param entity integer
---@return integer parent
function ecs.get_parent(entity)
end
---Enable component for entity
---@param entity integer
---@param component integer
function ecs.enable_component(entity, component)
end
---Disable component for entity
---@param entity integer
---@param component integer
function ecs.disable_component(entity, component)
end
---Test if component is enabled for entity
---@param entity integer
---@param component integer
---@return boolean
function ecs.is_component_enabled(entity, component)
end
---Add pair to entity
---@param subject integer
---@param relation integer
---@param object integer
function ecs.add_pair(subject, relation, object)
end
---Remove pair from entity
---@param subject integer
---@param relation integer
---@param object integer
function ecs.remove_pair(subject, relation, object)
end
---Test if an entity has a trait
---@param subject integer
---@param relation integer
---@param object integer
---@return boolean
function ecs.has_pair(subject, relation, object)
end
---Set relation of pair
---@param subject integer
---@param relation integer
---@param object integer
---@param value any
---@return integer
function ecs.set_pair(subject, relation, object, value)
end
---Set object of pair
---@param subject integer
---@param relation integer
---@param object integer
---@param value any
---@return integer
function ecs.set_pair_object(subject, relation, object, value)
end
---Get relation of pair
---@param subject integer
---@param relation integer
---@param object integer
---@param value any
function ecs.get_pair(subject, relation, object, value)
end
---Get mutable relation of pair
---@param subject integer
---@param relation integer
---@param object integer
---@return any
function ecs.get_mut_pair(subject, relation, object)
end
---Get object of pair
---@param subject integer
---@param relation integer
---@param object integer
---@return any
function ecs.get_pair_object(subject, relation, object)
end
---Get mutable object of pair
---@param subject integer
---@param relation integer
---@param object integer
---@return any
function ecs.get_mut_pair_object(subject, relation, object)
end
---Create a pair
---@param predicate integer
---@param object integer
---@return integer
function ecs.pair(predicate, object)
end
---Check if id is pair
---@param id integer
---@return boolean
function ecs.is_pair(id)
end
---Get object from pair
---@param pair integer
---@return integer
function ecs.pair_object(pair)
end
---Add a base entity to an entity
---@param entity integer
---@param base integer
function ecs.add_instanceof(entity, base)
end
---Remove a base entity from an entity
---@param entity integer
---@param base integer
function ecs.remove_instanceof(entity, base)
end
---Add a parent entity to an entity
---@param entity integer
---@param parent integer
function ecs.add_childof(entity, parent)
end
---Remove a parent entity from an entity
---@param entity integer
---@param parent integer
function ecs.remove_childof(entity, parent)
end
---Add override flag for component (forces ownership when instantiating)
---@param entity integer
---@param component integer
function ecs.override(entity, component)
end
---Deprecated, use ecs.override()
---@param entity integer
---@param component integer
function ecs.add_owned(entity, component)
end
---Create a bitmask component
---@param name string name
---@param descriptor string @format: "{name = constant, ...}"
---@return integer @entity
function ecs.bitmask(name, descriptor)
end
---Create an enum component
---@param name string name
---@param descriptor string @format: "{name, ...}"
---@return integer @entity
function ecs.enum(name, descriptor)
end
---Create an array component
---@param name string name
---@param type integer
---@param count integer
---@return integer @entity
function ecs.array(name, type, count)
end
---Create a struct component
---@param name string name
---@param descriptor string @format: "{type member; ...}"
---@return integer @entity
function ecs.struct(name, descriptor)
end
---Clone a component with a new name
---@param meta_type string @name
---@param alias string
---@return integer @entity
function ecs.alias(meta_type, alias)
end
---Get the value of an entity's component,
---returns nil if the entity does not have the component
---@param entity integer
---@param component integer
---@return table|nil
function ecs.get(entity, component)
end
---Get the value of an entity's component,
---adds the component if it doesn't exist,
---the second return value indicates whether it was added
---@param entity integer
---@param component integer
---@return table
function ecs.get_mut(entity, component)
end
---Patch component value without triggering OnSet systems, `copy` action.
---Returns true if component was added, false otherwise
---@param entity integer
---@param component integer
---@param value table
function ecs.patch(entity, component, value)
end
---Set the value of a component,
---equivalent to ecs.get_mut() + ecs.modified(),
---it does not trigger the `copy` component action
---@param entity integer
---@param component integer
---@param v table
---@return integer entity
function ecs.set(entity, component, v)
end
---Create a new reference
---@param entity integer
---@param component integer
---@return ecs_ref_t
function ecs.ref(entity, component)
end
---Get component value from cached reference
---@overload fun(ref: ecs_ref_t)
---@param ref ecs_ref_t
---@param component integer
---@return table|nil
function ecs.get_ref(ref, component)
end
---Get the value of a singleton component
---@param component integer
---@return table|nil
function ecs.singleton_get(component)
end
---Patch singleton component value, returns true if component was added
---@param component integer
---@param value table
---@return boolean
function ecs.singleton_patch(component, value)
end
---Set the value of a singleton component
---@param component integer
---@param value table
---@return integer entity
function ecs.singleton_set(component, value)
end
---Create a prefab
---@overload fun()
---@overload fun(name: string)
---@param name string
---@param signature string
---@return integer entity
function ecs.prefab(name, signature)
end
---Get child count, NOTE: creates a temporary iterator!
---@param entity integer
---@return integer
function ecs.get_child_count(entity)
end
---Set the current scope, returns previous scope
---@param scope integer
---@return integer
function ecs.set_scope(scope)
end
---Get the current scope
---@return integer
function ecs.get_scope()
end
---Set name prefix for newly created entities
---@param prefix string|nil
---@return string
function ecs.set_name_prefix(prefix)
end
---Create N new entities with an optional component
---@overload fun(n: integer)
---@overload fun(n: integer, noreturn: boolean)
---@overload fun(type: integer, count: integer)
---@param type integer
---@param n integer
---@param noreturn boolean @do not return the entity ID's
---@return integer[]
function ecs.bulk_new(type, n, noreturn)
end
local Component = ecs.lookup("Component")
ecs.bulk_new(10)
ecs.bulk_new(Component, 10)
--Does not return the entity ID's
ecs.bulk_new(10, true)
ecs.bulk_new(Component, 10, true)
---Get term from iterator
---@param it ecs_iter_t
---@param idx integer
---@return table
function ecs.term(it, idx)
end
---Returns all terms, including the entity array
---@param it ecs_iter_t
---@return any
function ecs.terms(it)
end
---Test if column is owned
---@param it ecs_iter_t
---@param column integer
function ecs.is_owned(it, column)
end
---Obtain the entity id of the signature column
---@param it ecs_iter_t
---@param column integer
---@return integer
function ecs.column_entity(it, column)
end
---Create a filter iterator
---@param filter ecs_filter_t
---@return ecs_iter_t
function ecs.filter_iter(filter)
end
---Progress the filter iterator
---@param it ecs_iter_t
---@return boolean
function ecs.fiter_next(it)
end
---Create a term iterator
---@param term integer
---@return ecs_iter_t
function ecs.term_iter(term)
end
---Progress the term iterator
---@param it ecs_iter_t
---@return boolean
function ecs.term_next(it)
end
---Progress the iterator
---@param it ecs_iter_t
---@return boolean
function ecs.iter_next(it)
end
---Create a query
---@param desc ecs_filter_t|string
---@return ecs_query_t
function ecs.query(desc)
end
---Create a subquery
---@param query ecs_query_t
---@param desc ecs_filter_t|string
---@return ecs_query_t
function ecs.subquery(query, desc)
end
---Create a query iterator
---@param query ecs_query_t
---@return ecs_iter_t
function ecs.query_iter(query)
end
---Progress the query iterator
---@param it ecs_iter_t
---@return boolean
function ecs.query_next(it)
end
---Check whether the query data changed since last iteration
---@param query ecs_query_t
---@return boolean
function ecs.query_changed(query)
end
---Create generic for loop iterator for a query/iterator
---NOTE: Jumping out of the loop will leave the last iteration's
---components unmodified.
---@overload fun(it: ecs_iter_t)
---@param query ecs_query_t
function ecs.each(query)
end
---Create a system
---@overload fun(callback: function, name: string, phase: integer)
---@param callback fun(it: ecs_iter_t)
---@param name string
---@param phase integer
---@param query string|ecs_filter_t @optional
---@return integer @entity
function ecs.system(callback, name, phase, query)
end
---Create an observer
---@param callback fun(it: ecs_iter_t)
---@param name string
---@param events integer|integer[]
---@param filter ecs_filter_t|string
---@return integer @entity
function ecs.observer(callback, name, events, filter)
end
---Run a specific system manually
---@overload fun(system: integer, delta_time: number)
---@param system integer
---@param delta_time number
---@param param any @optional
---@return integer
function ecs.run(system, delta_time, param)
end
---Set system context, sets ecs_iter_t.param
---@param system integer
---@param param any
---@return integer
function ecs.set_system_context(system, param)
end
---Create a snapshot
---@overload fun()
---@param it ecs_iter_t
---@return ecs_snapshot_t
function ecs.snapshot(it)
end
---Restore and collect snapshot
---@param snapshot ecs_snapshot_t
function ecs.snapshot_restore(snapshot)
end
---Create a snapshot iterator
---@param snapshot ecs_snapshot_t
---@return ecs_iter_t
function ecs.snapshot_iter(snapshot)
end
---Progress snapshot iterator
---@param it ecs_iter_t
---@return boolean
function ecs.snapshot_next(it)
end
---Create a module, export named entities
---to the optional export table
---@overload fun(name: string, callback: function)
---@param name string
---@param export table @optional
---@param callback function @import callback
---@return integer @entity
function ecs.module(name, export, callback)
end
---EXPERIMENTAL: Import a loaded module's named entities
---@overload fun(name: string)
---@param name string
---@param t any table @optional
---@return table|nil
function ecs.import(name, t)
end
---Print log message
function ecs.log(...)
end
---Print error message
function ecs.err(...)
end
---Print debug message
function ecs.dbg(...)
end
---Print warning message
function ecs.warn(...)
end
---Enable or disable tracing
---@param level integer
function ecs.log_set_level(level)
end
---Enable or disable tracing (DEPRECATED)
---@param level integer
function ecs.tracing_enable(level)
end
---Enable or disable tracing with colors
---@param enable boolean
function ecs.log_enable_colors(enable)
end
---Enable or disable tracing with colors (DEPRECATED)
---@param enable boolean
function ecs.tracing_color_enable(enable)
end
---Similar to the standard assert(), but the assertion
---will always succeed when built with -DNDEBUG
---@param v any
---@param message any
function ecs.assert(v, message)
end
---Get the size and alignment of a component
---@param component integer
---@return integer, integer
function ecs.sizeof(component)
end
---Get primitive type
---@param component integer
---@return integer|nil
function ecs.is_primitive(component)
end
---Preallocate a table with array/record elements
---@overload fun()
---@overload fun(narr: integer)
---@param narr integer optional
---@param nrec integer optional
---@return table
function ecs.createtable(narr, nrec)
end
---Set a component to be zero-initialized
---@param component integer
function ecs.zero_init(component)
end
---Get world pointer
---@return lightuserdata
function ecs.world_ptr()
end
---Get the constants from an enum or bitmask component
---@overload fun(type: integer)
---@overload fun(type: integer, out: table)
---@param type integer
---@param out table @optional table to merge with
---@param prefix string @prefix to omit from names
---@param flags string @convert to lowercase ("l")
---@return table
function ecs.meta_constants(type, out, prefix, flags)
end
---@class ecs_time_t
---@field sec integer
---@field nanosec integer
local ecs_time_t = {}
---Get the current time
---@return ecs_time_t
function ecs.get_time()
end
---Measure elapsed time for timestamp
---@param start ecs_time_t
---@return number
function ecs.time_measure(start)
end
---Set timer timeout
---@param timer integer
---@param timeout integer
---@return integer
function ecs.set_timeout(timer, timeout)
end
---Get timer timeout
---@param timer integer
---@return number
function ecs.get_timeout(timer)
end
---Set timer interval
---@param timer integer
---@param interval integer
---@return integer
function ecs.set_interval(timer, interval)
end
---Get timer interval
---@param timer integer
---@return number
function ecs.get_interval(timer)
end
---Start timer
---@param timer integer
function ecs.start_timer(timer)
end
---Stop timer
---@param timer integer
function ecs.stop_timer(timer)
end
---Set rate filter
---@param filter integer
---@param rate integer
---@param source integer
---@return integer
function ecs.set_rate_filter(filter, rate, source)
end
---Assign tick source to system
---@param system integer
---@param tick_source integer
function ecs.set_tick_source(system, tick_source)
end
---Create a new pipeline
---@param name string
---@param expr string
---@return integer
function ecs.pipeline(name, expr)
end
---Set a custom pipeline
---@param pipeline integer
function ecs.set_pipeline(pipeline)
end
---Get the current pipeline
---@return integer
function ecs.get_pipeline()
end
---Progress the world
---@param delta_time number
---@return boolean
function ecs.progress(delta_time)
end
---Set progress function callback
---@param cb function
function ecs.progress_cb(cb)
end
---Measure frame time
---@param enable boolean
function ecs.measure_frame_time(enable)
end
---Measure system time
---@param enable boolean
function ecs.measure_system_time(enable)
end
---Set target fps
---@param fps number
function ecs.set_target_fps(fps)
end
---Set time scale
---@param scale number
function ecs.set_time_scale(scale)
end
---Reset world clock
function ecs.reset_clock()
end
---Signal that the application should quit
function ecs.quit()
end
---Set number of worker threads
---@param threads integer
function ecs.set_threads(threads)
end
---Get the number of threads
---DEPRECATED: use ecs.get_stage_count()
---@return integer
function ecs.get_threads()
end
---Get current thread index
---DEPRECATED: use ecs.get_stage_id()
---@return integer
function ecs.get_thread_index()
end
---Get the number of stages
---@return integer
function ecs.get_stage_count()
end
---Get current stage id
---@return integer
function ecs.get_stage_id()
end
---EXPERIMENTAL: Create a new world,
---returns a new set of API functions tied to the world
---@return table
function ecs.init()
end
---EXPERIMENTAL: Destroy world,
---invalid for the default world
function ecs.fini()
end