Skip to content

Commit b3d11b4

Browse files
ThiagoUrielThiagoUriel
committed
Finished first steps for interaction. Fixes in other pages.
1 parent 18739bb commit b3d11b4

4 files changed

Lines changed: 183 additions & 13 deletions

File tree

‎Writerside/topics/combat/cbt_overview.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -38,26 +38,27 @@ assets and Blueprints, while deeper customization may require C++.
3838

3939
## Architecture Overview
4040

41-
Ninja Combat is organized around a dedicated combat domain layered on top of the Gameplay Ability System.
41+
Ninja Combat is organized around a dedicated combat domain layered on top of the Gameplay Ability System. The **combat
42+
domain is managed by a set of dedicated components**, orchestrated by a **centralized Combat Manager**.
4243

43-
Combat behavior is usually driven by abilities. Abilities can acquire targets, commit costs, trigger animation, apply
44-
damage, spawn projectiles, or route events into other combat systems. Damage is processed through a structured flow that
45-
can calculate mitigation, apply gameplay effects, trigger outcomes, and present feedback through Gameplay Cues.
44+
Combat behavior is usually driven by **Gameplay Abilities**. Abilities can acquire targets, commit costs, trigger animation,
45+
apply damage, spawn projectiles, or route events into other combat systems. Damage is processed through a **structured flow**
46+
that can calculate mitigation, apply gameplay effects, trigger outcomes, and present feedback through Gameplay Cues.
4647

4748
A key part of the architecture is the separation between **Damage Outcomes** and **Damage Cosmetics**. Outcomes represent
4849
authoritative gameplay results, such as applying damage, reacting to hits, notifying AI, or changing combat state. Cosmetics
4950
represent visual and audio presentation, such as hit flashes, floating numbers, camera feedback, or impact effects.
5051

51-
The plugin is designed to integrate with surrounding gameplay systems without owning them. Inventory can provide weapons
52-
and equipment, Input can activate combat abilities, Interaction can trigger combat-related abilities, and Ninja G.A.S.
53-
can provide the base Ability System setup.
52+
The plugin is designed to **integrate with surrounding gameplay systems without owning them**. [**Ninja Inventory**][10]
53+
can provide weapons and equipment, [**Ninja Input**][9] can activate combat abilities, [**Ninja Interaction**][11] can
54+
grant combat-related effects, and [**Ninja G.A.S.**][8] can provide the base Ability System setup.
5455

5556
## Integrations
5657

5758
- **[Ninja G.A.S.][8]** can provide the Ability System setup used by combat actors and abilities.
5859
- **[Ninja Input][9]** can activate combat abilities, combos, and gameplay events.
5960
- **[Ninja Inventory][10]** can provide weapons and equipment actors used by combat systems.
60-
- **[Ninja Interaction](int_overview.md)** can trigger combat abilities from interaction flows.
61+
- **[Ninja Interaction][11]** can trigger combat abilities from interaction flows.
6162

6263
[1]: https://www.unrealengine.com/marketplace/product/ninja-combat
6364
[2]: https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-for-unreal-engine
@@ -68,4 +69,5 @@ can provide the base Ability System setup.
6869
[7]: https://dev.epicgames.com/documentation/en-us/unreal-engine/umg-viewmodel
6970
[8]: gas_overview.md
7071
[9]: ipt_overview.md
71-
[10]: inv_overview.md
72+
[10]: inv_overview.md
73+
[11]: int_overview.md

‎Writerside/topics/interaction/core_concepts/interaction_system/int_interaction_source.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ optionally used to apply focus based on proximity.
7575
- **Required**. Must be present on each interaction source actor.
7676
- A shape component (commonly a box or sphere) used to **register interaction targets** so they can later be focused and interacted with.
7777
- This collider must be identified by the **Component Tag** `Interaction.Component.InteractableScan`.
78-
- This collider's **Object Type** should be `InteractionObject`, created during the [collision setup](int_collisions.md).
78+
- This collider's **Object Type** should be `InteractionObject`, created during the [collision setup](int_setup.md).
7979
<p><img src="int_source_component_scan.png" alt="Interactable Scan Collider" thumbnail="true" width="800" border-effect="line"/></p>
8080

8181
### Interactable Focus Collider

‎Writerside/topics/interaction/core_concepts/interaction_system/int_interaction_targets.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ of an interaction target, combining the component, interface, and visual represe
157157
1. Contains an **Interaction Target Component** with a fully configured Smart Object.
158158
2. Implements the **Interaction Target Interface**.
159159
3. Includes a mesh to visually represent the object.
160-
4. Provides a scene component with its collision set to the [**Interaction Target**](int_collisions.md) preset.
160+
4. Provides a scene component with its collision set to the [**Interaction Target**](int_setup.md) preset.
161161

162162
Ninja Interaction includes a core abstract base class and two ready-to-use subclasses:
163163

@@ -225,7 +225,7 @@ The following procedures will guide you through each step in detail.
225225
</step>
226226
<step>Assign your mesh asset, matching the one used in the Smart Object preview.</step>
227227
<step>
228-
Add a collision component (e.g., <b>Box Collision</b>) that matches the object’s shape, and set its <b>Collision Preset</b> to <code>InteractionTarget</code>, as per the <a href="int_collisions.md">collision setup</a>.
228+
Add a collision component (e.g., <b>Box Collision</b>) that matches the object’s shape, and set its <b>Collision Preset</b> to <code>InteractionTarget</code>, as per the <a href="int_setup.md">collision setup</a>.
229229
<p><img src="int_target_actor_02.png" alt="Set Collision Preset" border-effect="line" thumbnail="true"/></p>
230230
</step>
231231
<step>

‎Writerside/topics/interaction/int_first_steps.md‎

Lines changed: 169 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,170 @@
11
# First Steps with Ninja Interaction
2-
<primary-label ref="interaction"/>
2+
<primary-label ref="interaction"/>
3+
4+
This page guides you through the first steps for **Ninja Interaction**. Make sure to check the [**Interaction Setup**](int_setup.md)
5+
instructions before continuing. This page assumes that [**Ninja Input**](ipt_overview.md) is installed, but all concepts
6+
related to interaction inputs can easily transfer to plain Enhanced Input setups.
7+
8+
This page also assumes that [**Ninja G.A.S.**](gas_overview.md) is installed, but all concepts related to the Gameplay Ability System
9+
can easily transfer to other G.A.S. setups.
10+
11+
The following steps aim to provide **an interactable actor that can be detected by the player**. We will use the generic
12+
**Smart Object** and **State Tree** provided by Ninja Interaction.
13+
14+
## Interaction Targets
15+
16+
An **Interaction Target** is any actor in the world that responds to an interaction request from another actor, usually
17+
an **Interaction Instigator or Source**, such as a **player character** or **AI agent**. Their behavior is defined by
18+
two assets:
19+
20+
- **Interaction State Tree**: Defines each step that should happen when the interaction triggers.
21+
- **Interaction Smart Object**: Defines the usable slots and their configuration, including their state trees.
22+
23+
Ninja Interaction provides generic assets to get you started.
24+
25+
<procedure title="Create the Interaction Target Actor" collapsible="true" default-state="expanded">
26+
<step>Create a new Actor based on <code>NinjaInteractionActor_StaticMesh</code> (or use the Skeletal Mesh, <code>NinjaInteractionActor_SkeletalMesh</code>, variation if appropriate).</step>
27+
<step>
28+
Set the provided generic <b>Smart Object</b> to the <b>Interaction Target Component</b>.
29+
<p><img src="int_target_actor_01.png" alt="Assign Smart Object to Target Component" border-effect="line" thumbnail="true"/></p>
30+
</step>
31+
<step>Assign your mesh asset, matching the one used in the Smart Object preview.</step>
32+
<step>
33+
Add a collision component (e.g., <b>Box Collision</b>) that matches the object's shape, and set its <b>Collision Preset</b> to <code>InteractionTarget</code>, as per the <a href="collision_settings.md">collision setup</a>.
34+
<p><img src="int_target_actor_02.png" alt="Set Collision Preset" border-effect="line" thumbnail="true"/></p>
35+
</step>
36+
<step>
37+
Optionally, add debug strings to track interactions in relevant events such as <code>HandleTargetRegistered</code> or <code>HandleFocusRemoved</code>.
38+
<p><img src="int_target_actor_03.png" alt="Debug Event Strings" border-effect="line" thumbnail="true"/></p>
39+
</step>
40+
<step>
41+
Implement <code>FinishInteractionEvent</code>, which is invoked by the generic interaction State Tree.
42+
In this example, we'll simply apply a <b>Gameplay Effect</b> that grants health to the player.
43+
<p><img src="int_target_actor_04.png" alt="Finish Interaction Example" border-effect="line" thumbnail="true"/></p>
44+
</step>
45+
</procedure>
46+
47+
## Interaction Sources
48+
49+
An **Interaction Source** (sometimes also referred to as the _Instigator_) is a Pawn or Character, and it is defined by
50+
the presence of the **Interaction Manager Component**. Sources must have access to an **Ability System Component** and
51+
will often include two collision components used to **register** and **focus** Interaction Targets.
52+
53+
<procedure title="Add the Interaction Manager Component" collapsible="true" default-state="expanded">
54+
<step>Navigate to your Player Pawn or Character Blueprint or C++ Class.</step>
55+
<step>Add the <b>Interaction Manager component</b>, <code>NinjaInteractionManagerComponent</code>.</step>
56+
</procedure>
57+
58+
### Interactable Scan Collider
59+
60+
This **collision shape** (commonly a box or sphere) must be present on each interaction source actor. It is used to
61+
**register interaction targets** so they can later be focused and interacted with.
62+
63+
This collider must be identified by the **Component Tag** `Interaction.Component.InteractableScan` and the collider's
64+
**Object Type** should be `InteractionObject`, created during the [**Collision Settings**](collision_settings.md) setup.
65+
66+
<procedure title="Add the Interaction Scan Collider" collapsible="true" default-state="expanded">
67+
<step>In your main Pawn or Character, add a <b>Sphere Collision</b>.</step>
68+
<step>Set the component's <b>radius</b> to a reasonable value, like <code>800</code>.</step>
69+
<step>Add <code>Interaction.Component.InteractableScan</code> to the list of <b>Component Tags</b>.</step>
70+
<step>
71+
<p>Set the <b>Object Type</b> to <code>InteractionObject</code>.</p>
72+
<p><img src="int_source_component_scan.png" alt="Interactable Scan Collider" thumbnail="true" width="800" border-effect="line"/></p>
73+
</step>
74+
</procedure>
75+
76+
### Interactable Focus Collider
77+
<secondary-label ref="optional"/>
78+
79+
This **collision shape** (commonly a box or sphere) is optional and, if present, applies focus to targets nearby. If you
80+
are using other strategies to detect focus, such as the **player camera center**, then you don't need this component.
81+
82+
This collider is usually smaller than the **Scan Collider** and, similarly, must be identified by the **Component Tag**
83+
`Interaction.Component.InteractableFocus`. The collider's **Object Type** should also be `InteractionObject`.
84+
85+
<procedure title="Add the Interaction Focus Collider" collapsible="true" default-state="expanded">
86+
<step>In your main Pawn or Character, add a <b>Box Collision</b> and place it in front of the character.</step>
87+
<step>Set the component's <b>dimensions</b> to a reasonable value, like <code>50x50x100</code>.</step>
88+
<step>Add <code>Interaction.Component.InteractableFocus</code> to the list of <b>Component Tags</b>.</step>
89+
<step>
90+
<p>Set the <b>Object Type</b> to <code>InteractionObject</code>.</p>
91+
<p><img src="int_source_component_focus.png" alt="Interactable Focus Collider" thumbnail="true" width="800" border-effect="line"/></p>
92+
</step>
93+
</procedure>
94+
95+
### Gameplay Abilities
96+
97+
Two Gameplay Abilities must be granted to the Interaction Source so it can scan and execute interactions:
98+
99+
- `InteractionAbility_FindInteractableActor`: Scans the list of registered targets and, based on the **provided Scan Task**, selects the best candidate for focus or interaction.
100+
- `InteractionAbility_ExecuteInteraction`: Executes the selected interaction by bridging communication between the source and the target components.
101+
102+
<procedure title="Grant Interaction Abilities" collapsible="true" default-state="expanded">
103+
<step>
104+
<p>Create a new <b>Gameplay Ability Blueprint</b>, extending from <code>InteractionAbility_FindInteractableActor</code>. Name it <code>GA_Interaction_Scan</code>.</p>
105+
<ul>
106+
<li>If you are using the <b>focus box collision</b>, you can use the default <b>Interaction Task Class</b> (<code>AbilityTask_FindClosestInteractionTarget</code>).</li>
107+
<li>If you'd rather apply focus using the <b>player camera</b>, then change the task to <code>AbilityTask_TraceInteractionTarget</code>.</li>
108+
</ul>
109+
</step>
110+
<step>Create a new <b>Gameplay Ability Blueprint</b>, extending from <code>InteractionAbility_ExecuteInteraction</code>. Name it <code>GA_Interaction_Execute</code>.</step>
111+
<step>Create a <b>Gameplay Effect Blueprint</b> and name it <code>GE_InteractionSetup</code>. This will allow you to easily reuse the Interaction Setup across different Ability Setup assets.</step>
112+
<step>Open the Gameplay Effect and add a <b>Grant Gameplay Abilities</b> component.</step>
113+
<step>Add both Interaction Abilities to the list of granted abilities.</step>
114+
<step>In your <b>G.A.S. Setup</b>, add the Interaction Setup Gameplay Effect.</step>
115+
</procedure>
116+
117+
## Player Input
118+
119+
To **start** or **interrupt** interactions, all you need to do is call the related functions in the **Interaction Manager
120+
component**:
121+
122+
- `TryInitializeInteractionWithCurrentTarget`: Attempts to initialize an interaction with the target currently selected. An optional Gameplay tag can be used to specify a slot, when more than one is available.
123+
- `TryCancelCurrentInteraction`: Attempts to cancel an ongoing interaction with a target. An optional Gameplay Tag can be used to inform the cancellation reason.
124+
125+
These can be invoked by players, as a result of Input Actions, or by AI agents, from Behavior or State Tree tasks. When
126+
using [**Ninja Input**](ipt_overview.md), you can create a dedicated **Input Handler** to handle both states. The procedure
127+
below shows how to create that handler, but the same manager functions can be called from any input binding.
128+
129+
<procedure title="Create the Interaction Input Handler" collapsible="true" default-state="expanded">
130+
<step>
131+
<b>Create an Input Action</b> (e.g., <code>IA_Interact</code>).
132+
<ul>
133+
<li>Add a <b>Pressed</b> trigger.</li>
134+
<li><i>Optional:</i> add a <b>Released</b> trigger for hold-to-activate / cancellable interactions.</li>
135+
</ul>
136+
</step>
137+
<step><b>Create an Input Handler</b> that <b>extends</b> <code>NinjaInputHandler</code> (from Ninja Input), and implement <code>HandleTriggeredEvent</code>.</step>
138+
<step>Retrieve the <b>Interaction Manager</b> from the pawn associated with the <b>Input Manager</b>, and verify it is valid.</step>
139+
<step>
140+
<p>Branch on the incoming <b>Input Action Value</b> (convert to bool):</p>
141+
<ul>
142+
<li><code>true</code> &rarr; call <code>TryInitializeInteractionWithCurrentTarget</code></li>
143+
<li><code>false</code> &rarr; call <code>TryCancelCurrentInteraction</code> with reason tag <code>Interaction.Event.CancelledButtonPress</code></li>
144+
</ul>
145+
</step>
146+
<step>
147+
<p><b>Bind the handler</b> in your input setup (mapping context / action bindings) so it runs for <code>IA_Interact</code>.</p>
148+
<p><img src="int_integration_input_handler.png" alt="Input handler branching to start/cancel via Interaction Manager" border-effect="line" thumbnail="true"/></p>
149+
</step>
150+
<tip>
151+
<p><b>Boolean Value Conversion</b></p>
152+
<p>The conversion function is an <i>auto-cast</i> function, meaning <b>you won't be able to find it in the context menu!</b></p>
153+
<p>Instead, you must <b>drag</b> the Value parameter pin to the Branch's Condition parameter, to automatically create the conversion.</p>
154+
</tip>
155+
</procedure>
156+
157+
## Next Steps
158+
At this point, you have an **interactable actor** that can be detected by both **players** and **AI agents**, and can be
159+
interacted with, using a dedicated Input Handler or equivalent input code.
160+
161+
1. The interaction target actor was configured.
162+
2. The interaction source can register and focus targets.
163+
3. The interaction abilities can scan and execute interactions.
164+
4. Player input can start or cancel interactions.
165+
166+
From here, you can:
167+
168+
- Learn more about [**Interaction Targets**](int_interaction_targets.md), their assets and features.
169+
- Learn more about [**Interaction Sources**](int_interaction_source.md) and their features.
170+
- Add [**Animations**](int_adv_interaction_animations.md) to your interaction State Trees.

0 commit comments

Comments
 (0)