Unreal URLs and Hubs
Tim Sweeney
Epic MegaGames, Inc.
tim@epicgames.com
http://www.epicgames.com/
This document is a trade secret of Epic MegaGames, Inc.
Unreal URLs
Unreal uses the standard URL (uniform resource locator) syntax of the WorldWide Web for
identifying levels, entry options, and startup options. This approach unifies
Unreal's local level switching with its network play. A sample URL is:
unreal://server.site.name.com/levelname#teleportername?option1?option2?option3
A URL consists of the following parts.
- unreal://: This is the standard Unreal identifier, which enables Unreal
URL's to be recognized by Windows and your web browser. For example, if you include
"unreal://" at the beginning of the URL, you can use it as a hyperlink on a web
page; as a Windows shortcut; or type it in a Web browser like Internet Explorer. When
typing a URL from within Unreal, the "unreal://" part of the URL is optional.
- server.site.name.com: The internet address of the Unreal server.
If you don't include this part, the level is assumed to be local (not on the
Internet). For example, "unreal.epicgames.com".
- levelname: The name of the level to enter. The default is
Index.unr (similar to Index.html on web sites).
- #teleportername: The optional name of the teleporter to enter the level
through. If not specified, a playerstart is used. Servers may ignore this, for
example in deathmatch games, where the server spawns players at random playerstart
locations.
- ?option: One of the following URL options listed below.
The following are player URL options, which may be specified either when starting a
local game or entering a network game.
- ?name=playername: Specifies the name of the player who is entering.
Defaults to "player".
- ?password=passwordstring: If the server is password protected, gives
the player's password.
- ?team=teamname: Optional team of the player who is entering. Some
servers may ignore this and automatically assign the player a team.
- ?class=unreali.femaleone: Specifies the class of the player, such as
unreali.femaleone, unreali.maleone, etc. The player class corresponds to an UnrealScript
class that expands the engine.playerpawn class.
The following are server URL options, which may be specified either when starting a
local game, or starting a dedicated server. They are not recognized for clients who
are entering a network game, because the server options have already been set at that
point.
- ?defaultplayer=unreali.femaleone: Specifies the default class for
players who are entering the game, and who don't explicitly request a class.
- ?game=unreali.deathmatchgame: Specifies the class for the game rules,
for example unreali.singleplayergame or unreali.deathmatchgame. The game rules
correspond to an UnrealScript class that expands the GameInfo class.
In addition to these predefined URL options, licensees using the Unreal engine and
users creating mods can define entirely new options. The URL options are processed
in the GameInfo class in two places: InitGame parses the server options when the dedicated
server is started; and Login parses the player options when each client (either local or
remote) who connects to the server.
Several kinds of URLs are used commonly:
- levelname#teleportername: Switches to the level named
"levelname", entering at the teleporter "teleportername". Discards the
hub stack.
- levelname#teleportername?push: Saves the state of the current hub
level, and goes into the level named "levelname".
- levelname#teleportername?peer: Moves to a peer level in the current hub
hierarchy. The current level is not saved; therefore this is only useful for one-way
links.
- #teleportername?pop: Exits from the current level and returns to the
previously-pushed hub, at the specified teleporter.
- ?restart: Restarts the current level.
- ?failed: Clients go to this URL when they are playing on an Internet
server and the server disconnects them unexpectedly.
Unreal hub system
The Unreal engine supports "hub" levels using a "stack" of levels.
The level stack always contains at least one level (the current one you're
playing). When you go from a hub into a gameplay level, the hub will typically be
saved, you play the game level, then you return to the hub. The engine automatically
saves the state of the hub levels if you link your levels using the proper URL's.
Note: Unreal uses URL's to designate all level-travelling options such as the level to
travel to, the teleporter to enter through, and more. URL's are sort of ugly and
complex-looking, but they are extremely versatile in enabling single-play and network
levels to be linked together in many cool ways, so they are a necessary evil.
Here is an example that might help visualize the "level stack".
When you start gameplay, you enter Vortex Rikers. The hub stack looks like:
- Vortex Rikers (current level).
Then you exit Vortex Rikers into the first hub, which is linked with the URL
"fhub1#teleportername?peer". "fhub1" is the name of the level.
"#teleportername" gives the name of the teleporter to enter the level
through. The "?peer" option tells the engine that you're travelling to a
peer level that should replace the current level on the hub stack. The new level
stack looks like:
Now you go from the first hub into a gameplay level, Dig, using the URL
"dig#teleportername?push". The "?push" tells the engine to push
the current level onto the level stack, then move into a new level. The level stack
now looks like:
- Dig (current level).
- FHub1 (saved on disk).
Once you successfully complete Dig, you encounter a URL that sends you back to the hub,
"#newteleporter?pop". The "#newteleporter" names a new
teleporter to jump the player to within the saved level. "?pop" tells the
engine to pop the current level off the level stack, and return to the previous level.
The level stack now looks like:
The hub system should completely work with savegames. Each level in the hub stack
is saved in a different file in the \unreal\save directory.
The hub system supports hubs up to 10 levels deep. Of course, this would be
extremely confusing to players. For simplicity, in Unreal, we never go above 2
levels deep in our design.
Notes:
- To incorporate proper hub transitions, all links between levels need to be updated.
The new link URL's need to include the new "levelname#teleportername"
syntax (rather than the old "levelname/teleportername" syntax), and use
"?push", "?pop", and "?peer" where appropriate.
- It's very important that we plan all the links carefully to prevent junk from
accumulating on the level stack. For example, if you have five levels and you link
them all together linearly using "?push", all five levels will be saved on the
hub stack. You need to make sure to link all linear levels using "#peer",
and to make sure that all "?push" URL's are matched up with corresponding
"?pop" URL's.