vp_enter

From Virtual Paradise Wiki
Revision as of 17:39, 17 December 2016 by Sleepy E (talk | contribs) (Add example code)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Method call snippet vp_enter(instance, world);

Enters a bot into a world.

Parameters

These are the parameters that this method requires:

Parameter Usage
VPInstance
instance
Pointer to the instance this method call is intended for
string
world
Name of an online world to enter

Returns

This method returns a return code integer, which indicates whether the call was successful or errored for any reason:

Return code Cause
VP_RC_SUCCESS Successful call (for methods that have a registered callback, it only means the request has been sent)
VP_RC_STRING_TOO_LONG World name was longer than 255 bytes
VP_RC_CONNECTION_ERROR Disconnected from universe while sending, or connecting to the world failed
VP_RC_WORLD_NOT_FOUND No such world is connected to the universe
VP_RC_WORLD_LOGIN_ERROR Could not login to world (e.g. incorrect world address configured) or banned (not yet implemented)
VP_RC_TIMEOUT Connection attempt to the world server timed out (e.g. firewalled server)
VP_RC_NOT_IN_UNIVERSE Bot is not currently connected to universe

Behavior

  • If a VP_CALLBACK_ENTER callback is set this function will return immediately and return the result using the callback, otherwise it will call vp_wait() in a loop until done.
  • If the bot was already in a world, it will automatically leave that world.
  • Entering a world will trigger VP_EVENT_WORLD_SETTING for each world setting. Followed by VP_EVENT_WORLD_SETTINGS_CHANGED to signal that all settings have been sent. Provided that the instance has subscribed to them. See vp_event_set().

Caveats

  • The bot will not have a visible "presence" in the world (e.g. will not appear to other users or bots') until vp_state_change() is called at least once.
  • World names are case-sensitive.

Examples

bool g_receiving_world_settings;

void handle_world_setting(VPInstance sdk)
{
  if (!g_receiving_world_settings)
  {
    printf("Server is sending world settings...\n");
    g_receiving_world_settings = true;
  }

  const char *key, *value;

  key = vp_string(sdk, VP_WORLD_SETTING_KEY);
  value = vp_string(sdk, VP_WORLD_SETTING_VALUE);

  printf("World setting: \"%s\" = \"%s\"\n", key, value);
}

void handle_world_settings_changed(VPInstance sdk)
{
  printf("Server is done sending world settings.\n");
  g_receiving_world_settings = false;
}

int main(int argc, const char* argv[])
{
  // ...
	
  vp_event_set(sdk, VP_EVENT_WORLD_SETTING, handle_world_setting);
  vp_event_set(sdk, VP_EVENT_WORLD_SETTINGS_CHANGED, handle_world_settings_changed);

  int rc;

  rc = vp_enter(sdk, WorldName);
  if (rc)
    printf("Couldn't enter world(reason %d)", rc);

  // ...
}

See also