[Adonthell-devel] Equipment test

[Kai Sterker]

As promised, here's a first implementation of equipping items. It's not
very polished yet, but I hope it's something we can build upon.


How to run the test:
====================

Update your v0.3 CVS copy, build stuff, including tools. Make sure to
install, as the adonthell.py module is changed. Then untar the attached
package inside tools/pydonthell and run 'pydonthell manager_test.py'.
That's it.


What's inside:
==============

The most interesting part is certainly manager.cc/manager.h. That
contains the few methods we discussed about on friday. When coding
stuff, I noticed that we had forgotten a few details:

* item count

  As we agreed, a whole stack of items can be equipped (in case of
arrows and the like). That means, whenever equipping items, one has to
pass the count. However, that leads to one problem. When there is
already a stack equipped, how do you return it's size? After all,
manager::equip returns an item_base, but the count is kept with the slot
class. So I chose to use an inout parameter to return the count of the
returned item. Same is true for manager::unequip.

* moving items between equipment slots

  In that case, we must not forget to call item::unequipped. However,
how can the manager tell whether a given item sits in an equipment or a
normal slot? One way was adding a flag to the slot class (Equipment),
that contains exactly this information.
This has another advantage: we can now ensure that manager::equip does
not accept slots that aren't meant for equipment.

* adding items of the same kind

  For example, I have a slot with 10 items and want to add another 10 of
the same sort. In that case, the currently equipped items should not be
removed. Instead the given items should simply be added to the slot. In
the case that not all of them fit (because of stack size restriction),
the number of those remaining will be returned via the count parameter.

That means, no matter what the case, the return value will always
indicate whether any items have been left over, and the count parameter
will always give the right amount.


Apart from that, nothing should be really surprising. See the code or
CVS for the rest. If you spot bugs or have questions, please tell me.


What's missing:
===============

Currently, there's no integration with the character class. That's
mainly because I do not want to break compatibility with v0.3 in CVS,
and mainly because I didn't have *that* much time ;). But it's on the
todo list!


Issues:
=======

A problem that is quite severe is related to SWIG. As Python python does
not inout parameters, the Python wrappers of manager::equip/unequip
return a tuple instead of a single value. However, if the return value
of the method is NULL, then SWIG will discard it (see
py_adonthell_wrap.cc: t_output_helper(...)). That means, on Python side
I cannot write

   item, count = Manager.equip (slot, item, count)

as I might not get the item back in case it is NULL. I consider that a
flaw of SWIG. The problem is, we cannot really work around that. For
equip I can always return an item and use count to decide whether it is
valid. However, if someone calls unequip on an empty slot, there is no
item to return!

Do you think I should report this issue to the SWIG people and hope that
they change this behaviour? Or do you have another idea. (Using SWIG
1.3.19 here, btw.)



Another possible problem exists in slot::get_item, which isn't free of
side-effects. It does assign the slot to immutable items (which cannot
have a persistant slot assigned). That's what we want in most cases,
however, sometimes this shouldn't happen. Guess an optional parameter
could take care of that.


Questions left:
===============

I'm not exactly sure when to call item::equipped / unequipped. Right
now, unequipped is only called if the last item has been removed. Should
something similar be done with equipped: i.e. only call it when a new
item is equipped, but not when an item is added to an existing stack?


Bugs fixed:
===========

I believe that I found a bug in py_adonthell.i:

The string returned by '%typemap(python,out) string &' shouldn't be
deleted. After all, it's most likely a member of some class, which will
still need it.

Without that fix, my test script had segfaulted, because when calling
slot::id (), the id would be returned and also deleted(!).


Okay, that's been quite a lot for a single mail. Tell me of any

manager_test.tar.gz
Description: GNU Zip compressed data