Wiz Programming Tutorials

Wyvern uses lots of Lists, Sets, Hashes, Arrays, and other data structures in its arguments. This tutorial will show you how to read and manipulate them.

As an example, the wyvern.lib.GameMap interface has a getMonsterList() function that returns a Set of the monsters in the map. (Sadly, it's a poorly-named function - should have been called getMonsters()).

Quickie Definitions

There are four main kinds of data structures used in Wyvern:
  • List - a sequential, ordered list of items. You can get the first item, the second item, and so on.

  • Set - an unordered "bag" of items. They're not numbered, and they can be returned in any order.

  • Map - a set of unordered key/value pairs. By far the most common example is every game object's property list. The keys are property names, like "level", and the values are miscellaneous objects like Integers, Strings, Booleans, and Beans. Sometimes a Map is also called a "Dictionary".

  • Array - a sequential, ordered list of items, just like a List. You don't see them as often as you see Lists. There are some performance differences between Arrays and Lists, but nothing that you really need to care about right now.

Sometimes you'll see specific subclasses in the API, such as LinkedList, ArrayList, HashSet, HashMap, and TreeMap. Don't worry too much about those for now. The nice thing is that they're all accessed the same way, which we'll explain below.

Python has its own set of data structures (arrays, lists, maps, and so on) with its own specific language constructs for creating and manipulating them. You are more than welcome to use them for your own purposes. However, you'll need to use this code in this tutorial when you're manipulating Wyvern built-in data structures (since they're written in Java).

Many of the Wyvern game classes return one of the four standard data structures, or take one as a parameter. For example, there's a method called 

	wyvern.lib.GameMap.getObjectsAt(x, y)
That returns a List of the objects at location (x, y). The list is just like any other list, and you can do all the normal operations to it that we cover below.

Accessing Values

There are four fundamental operations for every data structure:
  • get() - retrieves an item from a data structure.

  • add() (or put() for Maps) - sticks an item (or key/value pair) into the data structure.

  • contains() - tells you if an object is contained in the data structure.

  • iteration - this is where you process every item in the data structure. It's got a special section below.

It's very convenient to have the List, Set and Map APIs bookmarked, so you should bookmark to this link:

Java 2 Platform API

It has the Javadoc API documentation for all the Java classes. The one you'll visit the most often is in the Java 2 Platform Packages (in the right frame), under the package java.util. It has the API definitions for all the data structures that Wyvern uses.

For example, you can click on the List interface, scroll down to the Method Summary, and see all the methods on List. You have all of these methods available to you in your Wyvern coding - in fact, you can call all of the thousands of methods in the entire Java API.

In fact, you actually have access to three complete API sets in Wyvern:

So your code in Wyvern is actually sitting on a truly gigantic bundle of code, all of which you can use freely for your coding. It helps to familiarize yourself with the tools you've got at your disposal!

Iterators

You access all the data structures above (except Arrays) using an Iterator. It goes through each item in the data structure and returns them to you one at a time. Here's the basic pattern: 

it = mylist.iterator()
<font color="blue">whilefont> it.hasNext():
    item = it.next()
    # ... do something with item ...

This works identically for Lists and Sets, except that for Sets, the items could come in any order.

For Maps, you can iterate over the keys or the values. To iterate over the keys, do this: 

it = mylist.keySet().iterator()
while it.hasNext():
    key = it.next()
    # ... do something with key ...

The best way to iterate over the values of a Map is to iterate over the keys, and pull out the value for each key, like so: 

it = mylist.keySet().iterator()
while it.hasNext():
    key = it.next()
    value = mylist.get(key)
    # ... do something with value ...

Deleting Items During Iteration

Sometimes you want to delete items from a data structure as you're going through it. You can't just say list.remove(item), because you'll get something called a ConcurrentModificationException when you try to do the next call to it.next().

Instead, the Iterator provides a remove() method for you. To remove "rhialto" from a list of names, you'd do this: 

it = namelist.iterator()
while it.hasNext():
    name = it.next()
    if name == 'rhialto':
        it.remove()

Arrays

Note: for experienced Python programmers: when we say "Array" here, we mean a Java array, such as 

	String[ ] names = { "Joe", "Fred", "Bob" };

You don't use Iterators to go through a Java array. Here's the pattern: 

for i in range(len(myarray)):
    item = args[i]
    ... do something with item ...

It's more or less like an Iterator. Here's a working example that shows you how to use it. In this case, we've written an object that provides a command called "argtest". When you type "argtest" followed by some arguments, it prints out the arguments you typed.

Note that we didn't actually parse the arguments - they come pre-parsed in the CommandEvent passed into Command.execute(). You can get them via event.getArgs(), which returns an Array of the arguments. 

from java.lang import String
from wyvern.lib import Command
from wyvern.kernel.maps import MapObject

class argtest(MapObject, Command):

    def initialize(self):
        self.super__initialize()

        # give it any old appearance
        self.setDefaultCategory("objects")
        self.setDefaultBitmap("jade_key")
        self.setProperty('short', 'arg tester')
        self.setProperty('desc', "type <font color="4169FF">'argtest [args]' to see your args"font>)

    def knowsCommand(self, cmd):
        return String.startsWith(cmd, "argtest ")

    def createEvent(self, event):
        return event

    def execute(self, event):

        agent = event.getAgent()

        # this returns a string array
        args = event.getArgs()

        for i in range(len(args)):
            agent.message(args[i])pre>

<< Previous Chapter Next Chapter >>