Teleporting Across Maps with Entity References

[JosephCatrambone]

First off, kudos to Trouv for making this library. It's proving to be very friendly and enjoyable to use. This is a curiosity which I'm "immortalizing" because I suspect others will encounter a similar architectural question when it comes to referring to things across maps. All that said, let's begin:

LDTK has the ability to link entities across levels. I'm using it my game to connect doors to exits across two different levels. In the platformer example, levels are changed when a player exits one side of the map. The connection between locations is implicit, but this isn't always the case, especially if one is "teleporting" via a door or portal.

When I create the door object inside of the map, it gets an Area2D assigned and a DoorDestination component. The DoorDestination is just a simple FieldInstanceEntityReference. Personally, I would rather just get the XY of the target location in the destination, but the new level isn't loaded, so it's not defined. I can think of a few ways to solve this but am not sure what's best.

fn level_door_interaction_system(
	mut level: ResMut<LevelSelection>,
	door_query: Query<(&Transform, &Area2d, &DoorDestination), Without<Player>>,
	mut player_query: Query<(&mut Transform, &RigidBody), With<Player>>,
) {
	// Check for collisions between the player and doors.
	let mut destination: Option<FieldInstanceEntityReference> = None;

	for (player_tf, player_body) in player_query.iter() {
		// Collide player with each door.
		for (door_tf, door_area, door_dest) in door_query.iter() {
			if let Some(_) = systems::minimum_separating_axis(&player_tf.translation.xy(), &player_body.size, &door_tf.translation.xy(), &door_area.size) {
				let door_dest: &DoorDestination = door_dest;
				// We are touching a door!
				destination = Some(door_dest.0.clone());
				break;
			}
		}
	}

	if let Some(dest) = destination {
		let dest:FieldInstanceEntityReference = dest;
		*level = LevelSelection::Iid(dest.level_iid);
		// Also translate the player to the target.
		for (mut player_tf, _) in player_query.iter_mut() {
// Oh no!  We can change the level but we don't know the new destination for the player!
		}
	}
}

Possible solutions:

1. Make a Transition resource which gets drawn on top and add a "teleport on complete" handle, but this feels like mixing a bunch of functionality in one system. The resource would have a "fade" amount, a fade direction, a destination level, and a destination position. The system will perform a fade and, when completely faded, change the level, then check for the loaded entity and set the player's transform correctly.

2. Hard-code the XY in the Entity attributes for doors. I don't like this one, but it's important to list it. LDTK does allow people to attach a Point attribute to entities, but there are issues related to linking across levels and problems with usability if the level gets moved around. (You need to update old references. Bleh.)

3. Attach a Teleport component to the player object which triggers a teleport when the desired object is loaded. This is not dissimilar to the first solution, but the component goes on a player and just checks for <Added> and then teleports. It's more specific than the general fade and doesn't do as much mixing of intents.

4. Make an Event and have the LDTK map loader actually teleport the player when an entity with the given UUID is spawned. This would be like a process_spawned_level_entity system but would use Events instead of Added<EntityInstance>. It makes me a little nervous because dropped events could leave the player in the void.

Thoughts are appreciated. I'll link the code when I've decided.

[JosephCatrambone]

Much of the difficulty seems to stem from an inability to search for UUIDs across levels. (It is possible this functionality does exist and I've simply not encountered it.) I wonder if the structure of LDTK worlds is such that a search for an entity can be done in a reasonable time? Would it be a mess? Are there other use cases for searching for a UUID across levels?

[janos-r]

I had the same issue. Your message helped me allot! Thank you.

This is my summary:
As it is now, it is necessary to have different entities for travel.

• within the level - teleports - with a Point field - triggered by collision
• outside the level - doors - with an Entity_ref field - triggered by collision + spawn of referenced entity
  • Not only is this more complicated, but because the travel happens in 2 steps, there is a frame of the already loaded level, before the door pics up the player.

In the source of this library, I saw a few things that give me the impression it should be possible to spawn more than just the entities within the current level. Have a look at LimitScope under EntityDefinition. It looks like something we are looking for, but I don't know if its possible to use it, or how.
There is also load_level_neighbors: true, that is shown in the platformer example, but as the name suggests, it doesnt give world-wide acces to certain entities as we would like.

My Door implementation:
https://github.com/janos-r/bevy-test/blob/520a8b985f9ad4e0954534028b5dd3736d296e15/src/components/door.rs