====== Subjects. The Low-Level Entities ======

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

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>