XShowGalaxy v1.22 README
By Andy McFadden (fadden@uts.amdahl.com)


WHAT IS XSHOWGALAXY?

This is essentially an X version of the "showgalaxy" utility which comes with
netrek.  It can only be used by Netrek (Xtrek II) server operators, because
it accesses the Netrek shared memory segment directly.

It has a number of improvements over the original "showgalaxy", including:

    - galactic and tactical displays on same screen
    - more detail, since it's X instead of curses
    - ability to lock onto a player or planet
    - ability to move around the game board as if you were playing (at up to
      warp 40 though)
    - ability to change player status, including:
      - player name (reset when they get killed)
      - team (F/R/K/O/I)
      - ship type (yes, instant refit on the fly, with shield/damage/fuel
	scaled proportionately; robots will retain any special abilities, like
	free torpedos and phasers)
      - shield/damage/fuel; options are heal (cure all, including wtemp/etemp),
	help (cure 10%), harm (damage 10%), and hose (damage fully - barely
	alive)
      - number of kills (+/- 1)
      - toggle shield status (kinda fun if timed correctly)
      - knock out of orbit
      - pacify (clear hostile and war)
    - ability to nuke (as with xtkill) or eject (forced self-destruct)
    - ability to modify planets, including:
      - planet name
      - ownership
      - special features (fuel/repair/agri)
      - number of armies (+/- 5, or Destroy)
    - ability to move players and planets to an arbitrary location (this does
      tend to freak people out though)
    - visible tractor/pressor beams
    - continuously updated player/planet display
    - larger "all messages" display, with optional message beep when a
      message sent to GOD is received
    - mouse warp to message window
    - some of the Options from Netrek, including update frequency, choice of
      planet bitmaps, view kill messages, show tactical planet names,
      and show shields
    - standard netrek Info dialogs (both 'i' and 'I')
    - optional support for Galaxy and AT&T ships and Iggy bitmaps
    - most of the items in the Options menu can be set in $HOME/.xsgrc
      (including updates/second, show shields, what to show on the galactic
      map, and whether or not to display xsg's "position")
    - uses the netrek ".sysdef" file for things like PLKILLS

It also has everything that showgalaxy had, including the ability to send
messages to players.

While you shouldn't be mucking around with people while they're playing a
serious game, it can prove invaluable when you want to test certain features
(you can damage robots, switch to an SB without having to play with .sysdef,
try fighting an SB Guardian, etc, etc.)  It's also possible to completely
re-sculpt the galaxy; you can rearrange all the planets, rename them, reassign
them fuel/repair/agri at will, etc.  Sort of a Netrek Galaxy Editor really.


COMPILING/INSTALLING:

For best results, put this in the netrek source hierarcy (i.e.,
	netrek/netrek/
	netrek/ntserv/
	...
	netrek/xsg/

I use a symbolic link to ../netrek/bitmaps.h and ../netrek/oldbitmaps.h;
didn't see any reason to transfer 230K of data around when you've already got
them on your system (they're part of the client code; every client
distribution should have them).  I also figured that some systems might have
customized bitmaps.  If you don't have your directories set up like mine,
just copy the headers or symlink them into the xsg directory.

You will have to do a minor customization to "defs.h"; the definition of
SYSDEF_FILE will have to be changed to whatever is appropriate for your system.

This ought to compile without problems on anything that will run netrek.
There is a section at the start of the Makefile which has a bunch of flags
for BSD/SYSV systems, ATT class ships, Galaxy class ships, scanning beams,
and the final Bronco release's full hostnames.  Make sure these are defined
correctly for your system before you try to compile.

I distributed this with x11window.c, but it should work equally well with
x10window.c or glwindow.c.  Should.  I don't have a setup where I can test
them, so if you can verify that it works, tell me.


To use this program, just run "xsg" (when the daemon is up) on the machine
that the server is running on.  Since xsg accesses the shared memory segment
directly, you MUST be on the same machine.  The help screen (hit 'h') shows
all of the commands.  It reads a few defaults from $HOME/.xsgrc (show
shields, message beep, window stuff).


KNOWN BUGS/GLITCHES:

(most of these are inherent in the Netrek client or server, so I can't fix them)

- When you change ship types, the shield/damage/fuel status bars are re-scaled,
  but they aren't erased before they're redrawn.  This can leave a splotch on
  the status display.  (Note this can also happen normally in the game if you
  refit while partially damaged.)

- Moving planets around causes the galactic map to get smeared (in the clients
  only; xsg redraws the screen automatically).  Refreshing the screen should
  remove the smear.

- You can't move a player who is orbiting a planet.  On the other hand, if
  you move a planet, all orbiting players move with it.  The "knock out of
  orbit" item on the "modify player" menu should be used to move an orbiting
  player.

- Netrek uses a 40x40 grid to determine which planets need to be redrawn on
  the galactic map.  If you put them too close together, the higher-numbered
  planet may become erased from the galactic map when somebody flies over it.

- Name changes to planets don't propagate to clients.  Only people who log in
  after the change is made will see it.

- The playerlist will show old data or possibly garbage as players are
  entering.  This is best fixed by fixing grabslot() in ntserv/enter.c
  to put "-" into p_name, p_login, and p_mapchars (two different places in
  the routine).

- There are conflicting definitions for Galaxy class cruisers (even the most
  "current" definition of the sources I grabbed had different #of max armies
  in netrek/getship.c and ntserv/getship.c).  When you change a ship type, xsg
  will use whatever numbers are compiled into it.  If you have a different or
  modified getship.c, you'll have to substitute it in.  You may also have to
  substitute sysdefaults.c if your ship defs depend on "chaos" mode or some
  other feature.

  (While it's not true in all cases, you should be able to simply copy your
  getship.c over the xsg copy.  If you want to use your sysdefaults.c, you
  may need to add some definitions to data.h and data.c.)

- Every great once in a while, the program will crash and report an X
  protocol error (i.e., something in x11window.c passed a bad value).  I'd
  suspect the X code, but I'm using the same routines that the game does.
  The error occurs at random, so there isn't much I can do about it (I
  suspect uninitialized data, but there's one hell of a lot of data used by
  this program...)


UPDATES/CHANGES:

- Added FULL_HOSTNAMES stuff to v1.22.
- Added independent (Iggy) bitmap support.  As usual, you need your own copy
  of the bitmaps.
- Tedd Hadley provided a number of improvements and bug fixes for v1.21,
  notably in the screen redraw stuff.


THAT'S ALL, FOLKS...

Please let me know if you find any bugs, or would like to see a certain
feature.  For bug reports, it's easiest to find them and fix them if you tell
me how to make them appear.

