Interactions and host hand-off
How one player pushes, hits, shoves or takes down another in a NEO session, what the host checks and how to tune it, and how your game's state carries over when the host leaves.
On this page
Players in a session can push, hit, shove and take each other down, and everyone sees the same thing. When the host leaves, the next host carries on from where the old one was. This page shows how a game uses both with neo_net.
A game made from the Starter template already does all of this. Read on if you want to change how it behaves, or if your game has its own player character.
How an interaction works#
Each game asks. Only the host decides.
- The attacker's game asks. It pushes an
InteractionRequesttoNetInteractions::request. Nothing plays yet. - The host checks it against the positions it accepted for both players, not the positions the attacker's game shows.
- Approved: every game in the session gets the same
NetInteractioninNetInteractions::landed, the same frame it arrives. That includes the attacker, the victim, everyone watching and the host's own game. The host also raises the victim's movement budget by the push, so the victim flying back isn't held back as a speed hack. - Refused: only the attacker's game hears, in
NetInteractions::refused, with the reason. Nobody sees anything. - Every game plays it on its own picture of the two characters. The victim's own game moves the victim, and the victim's position then reaches everyone as usual.
Over a real connection, a push lands on every machine 40 to 60 ms after it was asked for.
Asking for an interaction#
use neo_net::{InteractionRequest, NetInteractions, kind};
fn shove(mut interactions: ResMut<NetInteractions>, target: u64, direction: Vec3) {
interactions.request.push(InteractionRequest {
target, // the other player's id (a key of RemotePlayers)
kind: kind::SHOVE,
direction, // which way the victim is pushed: away from the attacker
strength: 2.0, // m/s of velocity change
detail: vec![], // up to 96 bytes of your own
});
}
fn play(interactions: Res<NetInteractions>) {
for i in &interactions.landed {
// i.attacker pushed i.victim: play it on both characters
}
for r in &interactions.refused {
// r.reason says why (a Refusal); r.reason.name() reads "too far", "cooldown", …
}
}| Field | What it is |
|---|---|
target | The victim's player id. |
kind | kind::PUSH, kind::HIT (a body flying into someone), kind::SHOVE or kind::TAKEDOWN. Your game can add its own (below). |
direction | The way the victim is pushed. |
strength | The velocity change in m/s. |
detail | Up to 96 bytes your game chooses. Everyone gets them back in the NetInteraction. Starter puts the paired animation its motion matching chose here, so both machines play the same one. |
A NetInteraction carries id, attacker, victim, kind, direction, strength, detail and the host's tick. A Refused carries id, target, kind and reason.
What the host checks#
The host refuses a request unless every check passes. The refusal names the first one that failed.
| Check | Default | Refusal |
|---|---|---|
| The kind exists. | push, hit, shove, takedown | UnknownKind |
| The target is another player who is connected. | UnknownTarget, Itself | |
| Not stronger than the kind allows. | push 6, hit 12, shove 6, takedown 8 m/s | TooStrong |
| Within reach, plus slack for lag: 0.75 m, and the victim's speed × 0.3 s. | push 1.6 m, hit 2.5 m, shove and takedown 2.6 m | TooFar |
| At about the same height. | within 1.2 m | HeightGap |
| The attacker faces the victim. Not checked for a hit. | within 80° | NotFacing |
| The push points away from the attacker. | WrongDirection | |
| Nothing is between their chests (your game's blocking test, below). | none set | Blocked |
| The pair isn't cooling down from their last one. | push 0.5 s, hit 0.6 s, shove 1 s, takedown 1.5 s | Cooldown |
| The attacker isn't asking too often. Going over counts against the player's flood score. | 2 a second, a burst of 4 | Rate |
A request the host can't read is refused as Malformed. When two players stand inside each other (0.3 m apart or less), facing and direction aren't checked.
When it approves, the host raises the victim's movement budget by the kind's knockback: 3 m for a push and a shove, 4 m for a takedown, 6 m for a hit.
Changing the checks#
The checks are InteractionRules, in NetSettings::host.interactions. Change them in any system; the host picks up changes as they happen.
use neo_net::{InteractionKind, NetSettings, kind};
fn tune(mut settings: ResMut<NetSettings>) {
let rules = &mut settings.host.interactions;
rules.kinds[kind::PUSH as usize].reach_m = 2.0;
rules.kinds[kind::TAKEDOWN as usize].cooldown_secs = 3.0;
rules.rate = 1.0;
// a kind of your own: its number is its place in the list (4 here)
rules.kinds.push(InteractionKind {
facing: false,
knockback_m: 8.0,
..InteractionKind::new("blast", 6.0, 20.0, 2.0)
});
}InteractionRules field | What it is | Default |
|---|---|---|
kinds | The kinds, by number: name, reach_m, max_strength, cooldown_secs, facing, knockback_m. InteractionKind::new(name, reach_m, max_strength, cooldown_secs) makes one that needs facing, with 3 m of knockback. | push, hit, shove, takedown |
lag_slack_m | Reach added for lag. | 0.75 m |
lag_secs | The victim's speed times this is added to the reach too. | 0.3 s |
max_height_m | The largest height difference. | 1.2 m |
facing_deg | How far off facing the attacker may be. | 80° |
direction_cos | How closely the push must point away from the attacker (the cosine of the angle). | 0.3 |
rate, burst | Requests a second per attacker, and how many may come at once. | 2, 4 |
line_of_contact | Your game's blocking test. | none |
contact_height_m | How high above each player's position the blocking test runs (chest height). | 1.0 m |
Plugging in your blocking test#
The host doesn't know your level. Give it a LineOfContact: a function that takes two points and returns true when nothing is between them. The points are in the same metres and axes as the positions your game sends, already raised to chest height.
use neo_net::{LineOfContact, NetSettings};
use std::sync::Arc;
fn blocking_test(mut settings: ResMut<NetSettings>, walls: Res<MyWalls>) {
if !walls.is_changed() {
return;
}
let walls = walls.clone();
settings.host.interactions.line_of_contact =
Some(LineOfContact(Arc::new(move |a, b| !walls.blocks(a, b))));
}Set it again when the level changes. Starter does this for you: it tests the level's boxes and refreshes the test when scripts move them.
Event channels 0xF0 and up are reserved#
The engine sends interactions and hand-off state as events on channels 0xF0 and up. Use channels below 0xF0 for your own NetEvents. An event your game pushes on a reserved channel is dropped with a warning, and the host never passes a player's event on those channels to anyone. That is what stops a player forging a landed push. neo_net::is_engine_channel(channel) tells you whether a channel is reserved.
Interactions in Starter#
In a Starter game, other players' characters are there for you:
- You bump into them. Only your character stops; theirs never gives way on your screen.
- Interact (E) and Takedown (F) work on them like on any character, and a ragdoll flying into them hits them.
- Each one is asked of the host. When it lands, both machines play the same pair of animations. The victim's own machine moves the victim.
Starter packs a ragdoll flag into the mode byte it sends with each player's state: bit 5 (neo_gameplay_kit::net::mode::RAGDOLL). When a player ragdolls, their character falls on everyone else's screen too, and gets up only when the player does. If your game reads remote players' mode itself, bit 5 means that player is ragdolling.
Host hand-off with state#
When the host leaves, the platform picks the next host and everyone reconnects to them. The new host carries on from the old host's state:
- every player's position and movement budget, so a hand-off isn't a free teleport;
- teleport requests the old host hadn't decided yet, and orders not yet carried out;
- interaction cooldowns;
- your game's own state, registered in
NetHandoff; - live player scripts: they keep running on every machine, and bans and pauses hold.
The host sends this to every player once a second, and soon after anything important changes. A player who joins gets it at once. In tests, the new host was hosting about 40 ms after the old one quit, and play resumed 0.66 to 0.74 seconds after.
Registering your game's state#
On the host, keep your state in NetHandoff by key. put stores a value as JSON. Changed entries go out to every player.
use neo_net::{NetHandoff, NetStatus};
#[derive(serde::Serialize, serde::Deserialize)]
struct Round { number: u32, scores: Vec<(u64, u32)>, ends_at: f64 }
fn share_round(status: Res<NetStatus>, round: Res<MyRound>, mut handoff: ResMut<NetHandoff>) {
if status.is_host {
handoff.put("round", &round.0);
}
}put only marks an entry as changed when its JSON is different, so calling it every frame is fine. An entry can be up to 64 KB, and all entries together up to 256 KB. On every other player, NetHandoff::state holds the host's latest entries, and get reads one.
Reading it on the new host#
For the one frame a player takes over hosting, NetHandoff::inherited holds the old host's entries. Read yours there and pick up where the old host stopped:
fn take_over(handoff: Res<NetHandoff>, mut round: ResMut<MyRound>) {
if let Some(r) = handoff.inherited::<Round>("round") {
round.0 = r;
}
}The new host's NetHandoff::state starts as a copy of what it inherited, so the entries keep going out until your game changes them. NetStatus::handoff shows what was inherited.
Live player scripting keeps its state under the key neo.script.live. Don't use that key for your own state.
Limits today#
- The attacker's own game plays a shove one round trip after the key press (40 to 60 ms on a good connection), because it waits for the host.
- If two players shove each other at the same instant, both land. Nothing is rolled back.
- Only a character's capsule is solid to other players. Arms and shoulders don't brush.
- Each machine plays an interaction from its own picture of the two characters, so their poses agree to within the replication lag (about 20 cm in Starter), not exactly.
- The new host can be up to a second behind the old one, and doesn't know anything the old host decided after its last update.
- A host that crashes, rather than quits, keeps hosting through the platform's 5-second grace before the next host takes over.
- A fallen player's name tag stays where they stood until they get up.
- Players who spawn on the same spot drag each other until they move apart.