API design for special movement actions #24
Replies: 9 comments 27 replies
-
Initiating air actionsThe instinctive way to design an API for a double jump is to add a
Tnua aims to maximize customizability, and the way to do it is to move those decisions to user systems. This means that Tnua itself will not know how many jumps the player is allowed to do midair. Instead, Tnua will provide a mechanism for the user system to determine the number of the next jump, and the user system will then select whether or not to jump and with which strength: // Very pseudocode
controls.jump = if jump_button_pressed() {
match next_midair_jump_number() {
0 => Some(1.0), // jump from the ground
1 => Some(0.6), // air jump is less powerful
2 => Some(0.2), // Second air jump is even tinier
_ => None // third air jump is not allowed
}
} else {
None
} |
Beta Was this translation helpful? Give feedback.
-
|
I'm thinking about having two components:
The idea, very vaguely, is to do something like this: if jump_button_pressed() {
let mut air_actions_counter = air_actions_counter.with(&mut air_actions_regulator);
let jump = match air_actions_counter.current() {
0 => Some(1.0),
1 => Some(0.6),
2 => Some(0.2),
_ => None,
};
air_actions_counter.this_frame(jump.is_some());
controls.jump = jump;
} |
Beta Was this translation helpful? Give feedback.
-
|
I'm not actually 100% sure I need Actually, I'll have to handle the case of repeated jumps when the player keeps holding the jump button. But maybe there are better ways to do that as well? For example, instead of |
Beta Was this translation helpful? Give feedback.
-
|
I agree with the idea of a TnuaAirActionsCounter to know where we are for the air actions but I'm not sure we need .is_grounded() since we already have this information in the TnuaPlatformerAnimatingOutput with the jump_velocity. By default I think tnua should allow multiple jumps by default and only prevent them if specified to do so. The only thing I'm not sure about is if it makes senses to to use TnuaPlatformerAnimatingOutput to know wether the player is jumping or not, since in this case we're not using for animations. |
Beta Was this translation helpful? Give feedback.
-
|
I don't think multiple jumps should be the default. It is extremely rare for a game to want to allow unlimited jumps, so virtually all games will need to regulate it - and if a game is making the extra effort to regulate it, it can easily put in the effort to configure the entity to allow air jumps. Even more so when that configuration consists of adding the very component that's used to regulate it. Games that don't allow air jumps, on the other hand, are much more common. Even more common than games that allow double jumps - but that could be because it is simpler to implement and simpler to design. And since they require no extra regulation, I see no reason why not to make it the default behavior. As for why I want
|
Beta Was this translation helpful? Give feedback.
-
|
Yeah I see what you mean, even though I feel like it seems natural to check if the player is grounded before the jump it does make sense to only allow one by default. The only thing that bothers me is that the TnuaAirActionsRegulator would contain the same thing as the TnuaPlatformerAnimatingOutput, but is you plan to add more things to it for the other air actions it does make sense as well. |
Beta Was this translation helpful? Give feedback.
-
Types of air actionsTnua already has jumps, and the air version should work the same as he ground action - the controls will specify the jump's height, and Tnua will calculate the initial vertical velocity required to reach that height. How would the API for the other types of actions work? Actions that I can think of:
Note that many of these interact with the environment. My vision is that some other mechanism will tell the user control system how the environment looks like, and then it would create environment-unaware air actions. These are a lot of actions, and I want to see if I can generalize them somehow. |
Beta Was this translation helpful? Give feedback.
-
|
Oh and I was thinking about a hover, like there is in Super Mario Land 2 Yoshi's Island, or like a jetpack, would something like this be a jump or implemented as a different action? |
Beta Was this translation helpful? Give feedback.
-
|
Ideally I would have generalized all these actions into a single one, and have different Wiki entries that explain how to implement each one. I practice we would probable have to group them into several generalizations. But I think hover and jetpack are similar in that regard. Both of them are about applying an upward force that's stronger than gravity, in order to keep the character above a certain vertical velocity. In hover's case that velocity is negative (or at least zero), and in jetpack it's positive (but still finite - we don't want to launch the character upward too fast), but that's just a number that the user control system will have to pass to Tnua. Also, in both actions we may or may not want a strong initial boost to reach above a certain starting velocity. For example, in the Yoshi's island example, if it gets applied when the character is falling at full speed we want to quickly break the fall first and only then apply a smaller upward acceleration. And if a player applies a parachute ability while falling, we'll also want to break the fall quickly first before maintaining the vertical acceleration that would fit the rest of the parachuting. One difference thing I've seen in Yoshi's Island is that once Yoshi reaches a certain positive upward velocity, the action ends. So maybe there needs to be some control on how long the ability is maintained after reaching the target vertical velocity? Actually, maybe it needs to be chained? So hover will be (e.g., very pseudo): [
TnuaAction::ShiftToVelocity { vertical: -1.0, max_acceleration: 100.0 },
TnuaAction::MaintainVelocity { vertical: -1.0 },
]And Yoshi style hover: [
TnuaAction::ShiftToVelocity { vertical: -1.0, max_acceleration: 100.0 },
TnuaAction::ShiftToVelocity { vertical: 1.0, max_acceleration: 5.0 },
]Or something like that. |
Beta Was this translation helpful? Give feedback.
-
|
I've managed to express most of them that way:
The ones I didn't
I've also noticed that very few actions use more than a single action in the sequence, and the ones that do use it for entry/exit, so maybe we don't need to support a sequence (which does make things more complicated)? |
Beta Was this translation helpful? Give feedback.
-
|
I like it! For the jump it does make sense to have it as an action as well, instead of a special case. Why is the glide more complicated? Is it not a float parachute style where you maintain velocity horizontally? |
Beta Was this translation helpful? Give feedback.
-
|
Gliding is not just parachuting with horizontal movement. It also means the vertical velocity is tied to the horizontal one - that you can dive down to get faster horizontally or climb up at the cost of horizontal speed. |
Beta Was this translation helpful? Give feedback.
-
Actions that use the environmentThis is about actions like wall jumping, ledge hanging, vaulting over obstacles, etc. My direction for design is that the actions themselves will not be aware of the environment geometry itself - Tnua will process a wall jump action the same even if there is no wall there. Instead, I'll provide a It'd look something like that (as always - very pseudo. And the rest of the API may not work as depicted here): if player_is_airborne() && player_is_pushing_jump() {
if let Some(direction) = direction_player_is_pushing() {
if let Some(surface) = spatial_sensor.surface_at_direction(direction) {
control.action = Some(TnuaAction::WallJump {
jump_height: 1.0,
wall_position: surface.position,
wall_normal: surface.normal,
});
}
}
}If a similar action was sent without a wall being there, Tnua would have made the character jump off an imaginary wall. It should not need the wall itself - only the data provided about it inside the action. |
Beta Was this translation helpful? Give feedback.
-
Multiple actions at onceWhat should happen if the user control system invokes multiple action motions at once? Should this be allowed? Won't the actions interfere with each other? |
Beta Was this translation helpful? Give feedback.
-
|
The way it seems to be done so far I don't think allowing multiple actions at the same time is the way to go. Is there even any game that allow this? But one thing to consider is how the inputs will be buffered, ie if I want to jump after a dash, how will this work? |
Beta Was this translation helpful? Give feedback.
-
|
Some kind of cancellation mechanism (like in fighting games)? I think the user control system will query Tnua about the current action, and then instruct it about whether or not to cancel it. At any rate, the reason I was thinking about combining actions was so wall jumps that add some horizontal velocity can be a combination of a jump and a dash. But maybe for these cases it would be simpler to have a single action that handles both. |
Beta Was this translation helpful? Give feedback.
-
Design idea - composition by axisMaybe the actions will be more flexible if they can declare individual behavior on up to 3 axes? A wallslide action, for example, will look like this: actions.set([
TnuaActionComponent {
project_on: TnuaProjection::Plane { normal: Vec3::Y },
operation: TnuaActionOperation::FixtateTranslation(position_where_the_character_slides),
..Default::default()
},
TnuaActionComponent {
project_on: TnuaProjection::Axis { direction: Vec3::Y },
operation: TnuaActionOperation::CapVelocity {
direction: -Vec3::Y, // required despite the axis
max_speed: 2.0, // this is the max slide speed. It's positive, but the direction is negative
},
max_acceleration: 5.0, // TBD - is this in addition to gravity?
..Default::default()
},
]);Any axes not covered by a |
Beta Was this translation helpful? Give feedback.
-
The polymorphism solutionThe action will be a trait object that accepts the action-less motor output (plus configuration, sensor-input, and custom state?) and can modify it. This means that each action will have to be written manually, but I can just provide a library of helpers for all the common actions. |
Beta Was this translation helpful? Give feedback.
-
|
Maybe the regular floating and the jumping can also be coded in the same way? That way they won't be calculated when an action is active. Also it'll probably simplify the code? |
Beta Was this translation helpful? Give feedback.
-
pub trait TnuaAction {
// Wish it could default to `()`, but apparently that's unstable
type State;
fn init_state(&self, ctx: &TnuaActionContext) -> Self::State;
fn lifecycle_status(
&self,
state: &Self::State,
ctx: &TnuaActionContext
) -> TnuaActionLifecycleStatus;
fn apply(
&self,
state: &mut Self:::State,
ctx: &mut TnuaActionContext,
motor: &mut TnuaMotor,
);
}
pub struct TnuaActionContext {
pub frame_duration: Duration,
pub platformer_config: &TnuaPlatformerConfig,
pub platformer_state: &mut TnuaPlatformerState, // actions may mutate this one
// more data?
}This can potentially grow in the future. Each action has a
Before pub enum TnuaActionLifecycleStatus {
/// The action cannot be stopped by anything the user does.
Uninterruptible,
/// The action will be stopped as soon as it no longer getting fed into the controls.
Stoppable,
/// The action can be cancelled into another action, but it'll continue if
// the user simply doesn't provide any action.
Cancellable,
/// The action is finished, even if the user is still holding the button.
// If the action is repeatable and the button is still held, a timer will
// start counting until it can be repeated.
Finished,
}Alternative APIpub trait TnuaAction {
type State: Default;
fn apply(
&self,
state: &mut Self:::State,
ctx: &mut TnuaActionContext,
being_replaced: TnuaActionLifecycleStatus,
motor: &mut TnuaMotor,
) -> TnuaActionLifecycleDirective;
}Here the action is getting a: pub enum TnuaActionLifecycleStatus {
/// There was no action in the previous frame
Initiated,
/// There was a different action in the previous frame
CancelledFrom,
/// This action was already active in the previous frame, and it keeps getting fed
StillFed,
/// This action was fed up until the previous frame, and now no action is fed
NoLongerFed,
/// This action was fed up until the previous frame, and now a different action tries to override it
CancelledInto,
}The action knows whether or not it is being replaced (though not by whom. I don't want to couple actions to each other), and can decide if it should keep going using: pub enum TnuaActionLifecycleDirective {
StillActive,
Finished,
}The other change here is that instead of having an This design means that when an action gets cancelled, both old and new actions will be able to modify the motor. But because they know about the existence of each other I'm going to leave this to the actions' discretion. |
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
ECS approachSimilar to the polymorphism approach, but uses ECS - modify the motor decision from user systems. While I'm usually all for ECS solutions, in this case I don't like it:
I think some of these problems can be avoided by spawning a new entity for the action. But that's still more overhead than the polymorphic approach. |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure we need to have the components for querying, won't the current action already be accessible in the animation output? Like you I think that this is not the way to go. |
Beta Was this translation helpful? Give feedback.
-
|
The querying I'm talking about is not the one done for animating (the animating is already done in a user system, and can query whatever it wants). It's the one done when calculating the actual physics for the action (what impulses and forces the motor should apply). An ECS approach will allow it to query whatever it needs, while a polymorphic1 approach only provides it with a predefined set of data, which I hope will be enough. Of course, polymorphic actions will be able to bring some data in the action itself (this, e.g., how I'm planning wall actions to get data about the wall they are actioning against) - but that requires the user to pass that data in the control system, so they need to be conservative with what data they require. Footnotes
|
Beta Was this translation helpful? Give feedback.
-
|
Oh alright, that makes more sense. |
Beta Was this translation helpful? Give feedback.
-
|
Thank you for your knowledge |
Beta Was this translation helpful? Give feedback.
-
|
I don't feel I've shared much knowledge in this discussion. I'm mostly trying to figure out this topic myself here. |
Beta Was this translation helpful? Give feedback.
-
Concrete API suggestion (polymorphic actions, jump is just another action, unified with action counter)controls.set_action(TnuaSetAction {
identifier: "jump",
action: tnua_actions::Jump(20.0), // move the height from the config to here, since it's no longer privileged?
allowed: TnuaActionAllowed::Grounded {
buffer: 0.2,
},
});This is a bit cumbersome, so maybe a fluent interface would be better: // The default `allowed` is Grounded { buffer: 0.0 }
controls.set_action("jump", tnua_actions::Jump(20.0)).allow_buffer(0.2);The identifier can be used to determine if the user switch action, to handle multiple action inputs (not combine them - just determine which one was the last to start), and to write in the animating output so that another system could handle the animation for the action. While these can be done with the
It'll work like this: // Must be called before setting actions this frame. Or maybe just call it
// `begin_frame()` and have it reset the movement vector as well?
controls.action_frame_begin();
if dash_input() {
controls.set_action("dash", tnua_actions::Dash(...));
}
if jump_input() {
controls.set_action("jump", tnua_actions::Jump(20.0));
}
As for
Initially I thought about also having a controls.begin_frame();
if tnua_state.is_grounded() {
*jumps_counter = 0;
} else {
match tnua_state.action_report() {
TnuaActionReport::Started("jump") => {
*jumps_counter += 1;
},
TnuaActionReport::Ongoing("jump") => {
// Can also do stuff in this case, but not this time
},
_ => {}
}
// Player stepped from a cliff
if jumps_counter == 0 {
jumps_counter = 1;
}
}
match jumps_counter {
1 => {
// Air jump is not as powerfull as regular jump
controls.set_action("jump", tnua_actions::Jump(10.0)).allow_always();
}
2 => {
// Second air jump is even less powerful
controls.set_action("jump", tnua_actions::Jump(5.0)).allow_always();
}
_ => {
// Note that this **is** the regular jump. If the player tries to jump
// a third time in the air it won't jump and instead buffer a jump in
// case they reach the ground soon enough after.
controls.set_action("jump", tnua_actions::Jump(20.0)).allow_buffer(0.2);
}
}(note that |
Beta Was this translation helpful? Give feedback.
-
|
If I want to make the regular movement itself an action too, I'll need another I wonder if an override mechanism (where once an action starts it gets priority over actions that were already being fed) will work for the fallback actions. They'll need, of course, their own state - so that once a non-fallback action is over they can go back to it. But if that's not good enough, I can always add a |
Beta Was this translation helpful? Give feedback.
-
|
Maybe instead of passing controls.set_action("jump", tnua_actions::Jump(10.0).allow_always());(note that this is a bit different than the similar looking line in the last snippet of the opening comment of this subdiscussion (#24 (comment)) because here |
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
|
If regular movement becomes an action, the last thing to remain that needs the I don't want every action to have to consider the rotation, but I don't mind if just the base movement does. Maybe the fallback action can always happen (in which case its more of a "basis" action than a "fallback" one), and the other action (jump/dash/whatever) will just refrain from overriding the rotation (unless it's an action that does need to control rotation)? |
Beta Was this translation helpful? Give feedback.
-
|
Handling multiple basis actions (actually, let's just call them "basis", and use "action" for the non-basis ones) may be trickier than I originally thought.
Obviously we want Y to be chosen. But to avoid storing all the fed actions in a big structure, we want to know that in advance. Say our control system looks like this: controls.set_basis(X { ... });
if cond_for_y() {
controls.set_basis(Y { ... });
}
if cond_for_z() {
controls.set_basis(Z { ... });
}When passing X, we don't know that Y is going to be passed in the same frame. With actions this is not an issue, because X was already done for and we'll just ignore it until we reach a frame where it does not happen. But now, we must store the Actually, the same holds for Y - we don't know yet if the Z will be called this frame, so it can't override it. Because using multiple basis is already going to change the entire controls scheme (e.g. - you'd want different actions for a swim basis than for a regular movement basis) I think it is reasonable to make the user ensure they only pass one basis per frame. Maybe even panic if multiple basis are passed? |
Beta Was this translation helpful? Give feedback.
-
I want to figure out the design for things like double jumps, air dashes, wall jumps, vaulting, gliding, etc...
It feels like these should all be connected. A wall jump is like a double jump, but when a wall is nearby. And maybe with an horizontal boost? But an horizontal boost is a dash. And the mechanism for detecting when an air dash is allowed should be connected to the mechanism for detecting when a double jump is allowed.
So I want to come up with a good design that takes them all into account.
Beta Was this translation helpful? Give feedback.
All reactions