[Home] [Downloads] [Search] [Help/forum]

MUSHclient scripting

Description of MUSHclient world function: world.GetWorld


Name GetWorld
Type Method
Summary Gets an object reference to the named world
Prototype IDispatch* GetWorld(BSTR WorldName);

View list of data type meanings

Description

Returns an object which can be used to refer to another world.

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworld (name)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

You could use a small variation on the examples above to write your own "send to all worlds" or something similar.

If more than one world has the same name, only the first one matching that name will be returned. If this is likely, use GetWorldIDList to get a list of unique IDs (identifiers) and then use GetWorldById instead of GetWorld.

VBscript example
' --------------------------------------------------
' Example showing sending a message to another world
' --------------------------------------------------

sub SendToWorld (name, message)
dim otherworld

  set otherworld = world.getworld (name)

  if otherworld is nothing then
    world.note "World " + name + " is not open"
    exit sub
  end if

  otherworld.send message

end sub
Jscript example
// --------------------------------------------------
// Example showing sending a message to another world
// --------------------------------------------------

function SendToWorld (name, message)
{
 var otherworld

   otherworld = world.getworld (name);

  if (otherworld == null)
    {
    world.note("World " + name + " is not open");
    return;
    }

  otherworld.send(message);

}

SendToWorld ("MyOtherWorld", "say Hi there");
PerlScript example
# --------------------------------------------------
# Example showing sending a message to another world
# --------------------------------------------------

sub SendToWorld {
 my ($name, $message) = @_;

 my $otherworld;

 $otherworld = $world->getworld ($name);

  if (!defined ($otherworld))
    {
    $world->note("World " . $name . " is not open");
    return;
    }

  $otherworld->send($message);

}

SendToWorld ("MyOtherWorld", "say Hi there");
Python example
# --------------------------------------------------
# Example showing sending a message all worlds
# --------------------------------------------------

def SendToAllWorlds (message):
  worldlist = world.GetWorldList
  if (worldlist):
    for w in worldlist : world.GetWorld (w).Send (message)

SendToAllWorlds ("say Hi there")
Lua example
-- --------------------------------------------------
-- Example showing sending a message to another world
-- --------------------------------------------------

function SendToWorld (name, message)

local otherworld

  otherworld = GetWorld (name)

  if otherworld == nil then
    Note ("World " .. name .. " is not open")
    return
  end

  Send (otherworld, message)

  -- alternative syntax:   otherworld:Send (message)

end -- of SendToWorld

SendToWorld ("MyOtherWorld", "say Hi there")
Lua notes
Since Lua does not use the COM (Component Object Model) interface getting world 
variables works differently than for other languages.

The function GetWorld returns a "userdata" item which contains the address of the other world.

You can pass this as the first argument to any MUSHclient function and that 
function will then be applied to the target world.

eg.

otherworld = GetWorld ('pennmush')

Send (otherworld, "sigh")  --> send "sigh" to 'pennmush' world


An alternative syntax is to put the world name first, followed by a colon (not a dot), 
like this:

otherworld:Send ("sigh")  --> send "sigh" to 'pennmush' world

Every function call that is passed a different world name is automatically checked to see
if the world is still open, so it is safe to use the world variable some time after
obtaining it (although an error will be raised if you do so).

You can protect function calls using pcall, so you might do this to see if the
world is still valid:

-- try to call WorldName for world 'otherworld'

ok = pcall (WorldName, otherworld)

if ok then
  Note "otherworld is OK"
else
  Note "otherword has closed"
end
Returns An object reference to the named world, if it was found.
Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.
In JavaScript use the test "== null" to see if the reference is to a valid world.
In PerlScript use the test "defined ()" to see if the reference is to a valid world.
In Python use the test "if (ref)" to see if the reference is to a valid world.
In Lua use the test "if ref == nil" to see if the reference is to a valid world.

See also ...

Function Description
GetWorldById Gets an object reference to the world given its unique ID
GetWorldList Gets the list of open worlds - returning their world names
Open Opens a named document

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.


Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes


Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes


View all functions

[Back]

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]