Important changes in the Xconq API

Important changes in the Xconq API

[Hans Ronne]

I have just checked in some changes in the Xconq API that may break
existing games or cause them to work differently. It has to do with the
role of connections and how they affect the ability of a unit to sit in a
cell. There used to be "extra" space for units available in cells that had
connections, since the connections also could store units. Unfortunately,
this caused serious problems with restoring saved games that could not
easily be solved. Saved units that had been sitting on a connection would
end up on the ground, thus blocking other saved units from access to the
spot where they had been sitting.

In an attempt to fix this problem once and for all, I have removed the
extra space within connections. This means that you must now have room for
a unit in a cell if you want it to enter that cell. unit-size-in-terrain
must therefore be set to something reasonable for the cell terrain, and
there must be free space in the cell, whether or not there is a connection
present. Setting unit-size-in-terrain to something larger than that
terrain's capacity (e.g. 99) should only be used for terrain that you don't
want a unit to be able to enter even if there is a connection.

So how do you prevent a unit from entering a certain terrain type but
permit it to do so if there is a connection? Just use a large
mp-to-enter-terrain (e.g. 99) for that unit and terrain type, but make
mp-to-traverse small (e.g. 1) for the same unit and the connection. The
unit will then use the latter smaller mp value if a connection is present
and thus be able to enter the cell. It is also important that
mp-to-enter-terrain is zero or small for the connection.

Game designers sometimes try to limit unit movement by setting vanishes-on
or wrecks-on to 1 for certain terrains and unit types. Please be aware,
however, that this does not prevent a unit from entering the terrain. It
just kills the unit if you do so. In most of the existing games, you never
see this happen since movement into hostile terrain is blocked by
mp-to-enter-terrain being high. However, there are exceptions. One is if
you give the "Disembark" command to a unit thsat sits on a transport in the
standard game. The unit will then jump overboard and drown, since it
doesn't have to move into another cell. On the other hand, trying to jump
overboard by clicking on an adjacent sea cell will not work, since this
move is blocked by a high mp-to-enter-terrain for land units.

Another example where you can wreck a unit by moving into hostile terrain
is in the Voyages/Magellan game. Here, ships can enter land cells (unlike
most other games) but since wrecks-on is true for ships and land, they will
wreck and form a fort (presumably built by the shipwrecked crew).

To sum things up, here are the three most important points:

1. The recommended way to restrict unit movement is to use a high
mp-to-enter-terrain to block movement and a low mp-to-traverse to permit it
in the presence of a connection. This will prevent both the human player
and the AI from accidentally moving units into terrain where they will
perish.

2. The terrain capacity and unit-size-in-terrain should now only be used to
control the total number of units that can sit in a cell, but not to
prevent a specific unit type from entering that terrain. Do that with
mp-to-enter-terrain instead.

3. The vanishes-on and wrecks-on tables should only be used if you want a
unit to be able to enter a terrain, but then vanish (or wreck). They are
unnecessary in most games and can be left at their default values. Don't
try to use these tables to limit unit movement. Do that with
mp-to-enter-terrain instead.

I think most of the games in the library conform to these rules, but I have
not had time to check all of them yet. Bug reports are welcome.

Hans

Re: Important changes in the Xconq API

[Jim Kingdon]

> There used to be "extra" space for units available in cells that had
> connections, since the connections also could store
> units. Unfortunately, this caused serious problems

Getting rid of this is probably right.

A long time ago I remember some kind of bug in the standard game
whereby I had a ship and would then click on a river (where the river
was between two land cells), and the ship would just disappear rather
than sailing down the river (I was new to xconq, so I'm sure there was
plenty I didn't understand - not least of which that ships are a poor
use of construction points in the standard game, but I digress.  So I
don't really know exactly what I did, but I'm pretty sure that the
ship really did disappear).

I don't know if your fix would be related, but the fix does sound
right.  Seems like games should use mp-to-enter-terrain rather than
the extra space you describe.

Re: Important changes in the Xconq API

[Eric McDonald]

Here is another doc patch that reflects Hans' recent changes, plus removes a
redundancy from the game design manual.

The patch does the following to doc/refman.texi:
* Removes a duplicate entry of the UnitProperty, size, in the section on
advanced unit types.
* Makes some new notes regarding the unit-size-in-terrain table.
* Remarks that the capacity-negation table has been pulled from GDL.

Patch below:

--- orig-refman.texi	Sat Jun 21 23:30:43 2003
+++ refman.texi	Sun Jun 22 00:10:43 2003
@@ -2936,10 +2936,6 @@
 This property is true if the type is an advanced type.
 @end deffn

-@deffn UnitProperty @code{size} n
-This property is the size of the advanced unit.
-@end deffn
-
 @deffn TableUA @code{size-limit-without-advance} u a -> n
 This table indicates the maximum size of a unit of type @var{u} if the
 advance @var{a} has not been achieved.  Defaults to a large number.
@@ -3410,8 +3406,17 @@

 @deffn TableUT @code{unit-size-in-terrain} u t -> n
 This table is the ``size'' of a (full-sized) unit @var{u} when it is
-in/on the terrain @var{t}.  Defaults to @code{1}.  (Note that this is
-not the same as the size property of an advanced unit.)
+in/on the terrain @var{t}.  Defaults to @code{1}.@*
+NOTE: This is not the same as the size property of an advanced unit.@*
+NOTE: As of Xconq 7.5, this property is ignored for connection terrain
+types. Connectors (roads, for example) now refer to @var{u}'s size in the
+terrain that contains the connector rather than @var{u}'s size in
+connector @var{t}.@*
+NOTE: If you wish to prevent a unit's entry into @var{t}, then use the
+@code{mp-to-enter-terrain} table, and not this one. The implication of
+using @code{unit-size-in-terrain} to prevent entry is that the unit will
+not be able to enter any connectors in @var{t} if @var{n} is set too
+large.
 @end deffn

 @deffn TableUT @code{terrain-capacity-x} u t -> n
@@ -3425,6 +3430,7 @@
 unit in a cell to override any capacity due to connections in that cell.

 @deffn TableUT @code{capacity-negation} u t -> t/f
+@i{This table has been removed and is no longer available.}
 @end deffn

 @deffn UnitTypeProperty @code{stack-order} n

Re: Important changes in the Xconq API

[Jim Kingdon]

> * Remarks that the capacity-negation table has been pulled from GDL.

I don't understand this one.  unit.c (can_occupy_conn_1) has a
reference to ut_capacity_neg.

Re: Important changes in the Xconq API

[Hans Ronne]

>> * Remarks that the capacity-negation table has been pulled from GDL.
>
>I don't understand this one.  unit.c (can_occupy_conn_1) has a
>reference to ut_capacity_neg.

can_occupy_conn_1 is part of the connection code that I removed.

Hans

Re: Important changes in the Xconq API

[Lincoln Peters]

Another approach might be to make the terrain incapable of holding a
unit (i.e. set unit-size-in-terrain to 99) and set exclusive capacity
via terrain-capacity-x.  It would probably be the best solution for
trains on railroads, trucks on highways, etc., unless more than one type
of unit is supposed to use the connection.

Re: Important changes in the Xconq API

[Hans Ronne]

>Another approach might be to make the terrain incapable of holding a
>unit (i.e. set unit-size-in-terrain to 99) and set exclusive capacity
>via terrain-capacity-x.  It would probably be the best solution for
>trains on railroads, trucks on highways, etc., unless more than one type
>of unit is supposed to use the connection.

Yes. I believe terrain-capacity-x was originally introduced in order to
make it possible for aircraft to enter any cell, even if full with ground
units. Which does make sense. But you could of course also use it for
trains etc. In that case, you would provide extra dedicated space for
trains in every cell, just like the for aircraft, and then let
mp-to-enter-terrain and mp-to-traverse restrict movement to railroads. The
benefit would be that trains could move unimpeded by ground units (and also
by each other if the dedicated space is big enough).

What will not work after my latest changes is to use terrain-capacity-x to
restrict trains to cells with railroads, since connections no longer have
their own space (and capacities). You can still define capacity and
capacity-x for auxiliary terrain types, but these are now just dummy
numbers that are not used by the code. So you would have to use
mp-to-enter-terrain to keep the trains on the tracks.

BTW, each unit type can have its own dedicated space, so you can certainly
use this feature with more than one type.

Hans

Re: Important changes in the Xconq API

[Eric McDonald]

On Sun, 22 Jun 2003, Jim Kingdon wrote:

> > * Remarks that the capacity-negation table has been pulled from GDL.
>
> I don't understand this one.  unit.c (can_occupy_conn_1) has a
> reference to ut_capacity_neg.

I based this one on what Hans told me and by looking in table.def. Since it is
not in table.def, it should no longer be available to the audience the
documentation is addressing.

  Regards,
    Eric

Re: Important changes in the Xconq API

[Jim Kingdon]

> can_occupy_conn_1 is part of the connection code that I removed.

Oh, I see.  I had neglected to run "cvs update" before I looked for
whether capacity-negation was there.

I've checked in Eric's patch to refman.texi.

Patch: tkmap.c

[Eric McDonald]

Jim, thanks for applying my other patches. Here is another one.

The following tiny patch addresses a warning issued by at least one compiler's
(gcc) preprocessor:

--- orig-tkmap.c	Tue Jun 24 01:00:41 2003
+++ tkmap.c	Tue Jun 24 01:01:22 2003
@@ -4230,7 +4230,7 @@
 	the interface freeze. */
 	XDrawLines(dpy, d, gc, points, 5, CoordModeOrigin);
     }
-#endif MAC
+#endif /* MAC */

     XFlush(dpy);
     XSetFunction(dpy, gc, GXcopy);