Both sides previous revision Previous revision Next revision | Previous revision |
en:toolworks:docs:apparatus:subject [2021/10/19 09:53] – vladius | en:toolworks:docs:apparatus:subject [2021/12/06 22:36] (current) – vladius |
---|
====== Low-level Subjects ====== | ====== Subjects. The Low-Level Entities ====== |
| |
Subjects are pretty minimalistic entities managed by Apparatus itself. They are mostly UE-independent and consist of [[en:toolworks:docs:apparatus:trait|Traits]]. | //Subjects// are the foundational lightweight entities managed by Apparatus. They are mostly UE-independent and consist of [[en:toolworks:docs:apparatus:trait|Traits]] and [[en:toolworks:docs:apparatus:flagmark|Flags]]. |
| |
| ====== Subject Handles ====== |
| |
| Subjects are not used directly and their internals are hidden deep from the framework user's perspective. Instead a special concept called //Subject Handle// is introduced. It's really much like a [[ue>ProgrammingAndScripting/ProgrammingWithCPP/UnrealArchitecture/SmartPointerLibrary/WeakPointer|weak pointer]] in terms of Unreal. When you despawn a Subject all of the handles that are currently referencing it become automatically invalid. Internally this is managed through a generation-based referencing technique. |
| |
| ====== Subjective Layer ====== |
| |
| A Subject can have an additional higher-level dimension called [[en:toolworks:docs:apparatus:subjective|Subjective]]. Subjectives are UE-managed objects (UObjects) which may contain the high-level [[en:toolworks:docs:apparatus:detail|Details]] in their composition. Subjectives with Details are generally more flexible and have additional features implemented as compared to raw Subjects with Traits. This comes at a cost of being not as memory-/cache-efficient and potentially less performant. Please note however, that the Subjective layer is optional and you may establish your project's logic entirely on Subjects if you want. |
| |
| Subjects without the Subjective layer involved are called //barebone// Subjects. Both Subjective-based Subjects and barebone Subjects are commonly referred to as just //Subjects//. That's because every Subjective is actually a Subject internally and embeds it as an essential part. This is something like an inheritance, so every Subjective can also have Traits and Flags as part of its composition. |
| |
====== Spawning ====== | ====== Spawning ====== |
| |
| //Spawning// is a process of creating a Subject as part of a Mechanism. |
| |
| ===== C++ Workflow ===== |
| |
| In order to spawn a new Subject within the Mechanism, you should call one of the [[appi>class_a_mechanism.html#a6a4cad7d03e86cc6c32b0bb27780a71d|SpawnSubject]] methods. The simplest one would be:<code cpp> |
| FSubjectHandle Subject = Machine::SpawnSubject(); |
| </code> |
| |
| If you want to spawn a Subject with some Traits initially attached to it, use the special templated version of the method:<code cpp> |
| FBurning Burning{10, 15.5f}; |
| FSword Sword{2}; |
| FSubjectHandle BurningSword = Machine::SpawnSubject(Burning, Sword); |
| </code> |
| This would efficiently pre-allocate a Slot for the Subject in the correct Chunk and initialize it according to the Traits supplied as the arguments. |
| |
| ===== Blueprint Workflow ===== |
| |
| Spawning Subjects in Blueprints is done with a dedicated Spawn Subject node: |
| |
| {{:en:toolworks:docs:apparatus:spawn-subject-node.png?nolink|Spawn Subject Node}} |
| |
| You may also specify a starting set of [[en:toolworks:docs:apparatus:flagmark|flags]] via the corresponding pin argument. |
| |
| ====== Despawning ====== |
| |
| The //despawning// process is exactly the opposite of spawning and basically means destroying of a Subject. Destroying an already despawned (or invalid) Subject Handle is a legal operation that does nothing and reports no errors. |
| |
===== C++ Workflow ===== | ===== C++ Workflow ===== |
| |
| In order to destroy a Subject in your C++ code, use the [[appi>struct_f_subject_handle.html#ada8e65dcf50ee385748d6de603ccd4e4|Despawn]] method provided by the Handle structure. Do it like so:<code cpp> |
| void PickPowerup(FSubjectHandle Player, FSubjectHandle Powerup) |
| { |
| // Add health/energy/strength to the player... |
| ... |
| |
| // Remove the item from the world: |
| Powerup.Despawn(); |
| } |
| </code> |