NEOLearn

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.

Updated October 20, 2026

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.

  1. The attacker's game asks. It pushes an InteractionRequest to NetInteractions::request. Nothing plays yet.
  2. The host checks it against the positions it accepted for both players, not the positions the attacker's game shows.
  3. Approved: every game in the session gets the same NetInteraction in NetInteractions::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.
  4. Refused: only the attacker's game hears, in NetInteractions::refused, with the reason. Nobody sees anything.
  5. 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#

Rust
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", …
    }
}
FieldWhat it is
targetThe victim's player id.
kindkind::PUSH, kind::HIT (a body flying into someone), kind::SHOVE or kind::TAKEDOWN. Your game can add its own (below).
directionThe way the victim is pushed.
strengthThe velocity change in m/s.
detailUp 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.

CheckDefaultRefusal
The kind exists.push, hit, shove, takedownUnknownKind
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/sTooStrong
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 mTooFar
At about the same height.within 1.2 mHeightGap
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 setBlocked
The pair isn't cooling down from their last one.push 0.5 s, hit 0.6 s, shove 1 s, takedown 1.5 sCooldown
The attacker isn't asking too often. Going over counts against the player's flood score.2 a second, a burst of 4Rate

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.

Rust
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 fieldWhat it isDefault
kindsThe 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_mReach added for lag.0.75 m
lag_secsThe victim's speed times this is added to the reach too.0.3 s
max_height_mThe largest height difference.1.2 m
facing_degHow far off facing the attacker may be.80°
direction_cosHow closely the push must point away from the attacker (the cosine of the angle).0.3
rate, burstRequests a second per attacker, and how many may come at once.2, 4
line_of_contactYour game's blocking test.none
contact_height_mHow 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.

Rust
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.

Rust
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:

Rust
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.

See also#