========================================================================
 Jedi Knight Level

 P56.GOB

 A dry room with a pool in the floor and an air tank leaning on the
 wall. Press Use on the tank and you are a diver: in the suit at once,
 breathing like Vader after two seconds under water, and safe from
 drowning for as long as you hold it. It is built to be lifted into
 another level: three files, one template and one placed cog.

 [cogfactory / p56-scuba]

 BUILD 6  --  2026-09-30   (first packaged 2026-09-22)
 sha256 e4f095470ef9658e575b302b9fb42bbb

 This level is not made or distributed by LucasArts
 Entertainment Co.
========================================================================

THIS PACKAGE
------------------------------------------------------------------------
  P56.GOB          the level
  readme.txt       this file
  screenshot.jpg   what it looks like

INSTALLATION
------------------------------------------------------------------------
Drop P56.GOB into the `episode` folder of a Jedi Knight install (the one
that already has JK1.GOB in it) and pick it from the episode list.
Nothing else needs to change: the GOB carries its own level, cogs,
models, materials and sounds, and reads the stock resource/ for
everything else.

On a libretro frontend such as RetroArch, unzip first and put P56.GOB in
the episode folder of your Jedi Knight folder, then load it from there.
The core treats the folder above the GOB's folder as the game folder,
reads the episode from episode/P56.GOB inside it, and will not start
unless that folder also holds resource/ (Res2.gob) from a real install.

CONTROLS
------------------------------------------------------------------------
  Use (Space) on the tank takes the gear -- look down at it, it is small
  Use (Space) on the tank again to hand it back
  F1 toggles the external camera, to see the suit

NOTES
------------------------------------------------------------------------
  the suit is on from the moment the tank is taken until it is handed
  back, in or out of the water, and the air is unlimited. Both are the
  cog's defaults; one number each in the level's COGS row changes them
  (see ADDING IT TO YOUR OWN LEVEL)

  the tank is a locker, not an inventory item: it stays on the wall,
  and every take is a full tank

  the breathing loop starts after 2 seconds under water and stops at
  the surface

  with the default unlimited tank there is no text on screen at all. A
  finite tank says Scuba tank: 75% air, then 50%, 25% and 5%, then
  Scuba tank empty! -- and when it empties the suit comes off 2
  seconds later and drowning resumes

  everything named scb* is the kit; everything named p56*, and
  scuba.jkl, is this demo room and is not meant to be copied into
  another level

  five of the diving suit's seven textures in this GOB are flat-colour
  stand-ins (divetank, wetsuit, divereg, divelense, cressifins);
  darker.mat and bluesuede.mat are the real ones

  tested in OpenJKDF2 only; retail JKDF2 has not run it

ADDING IT TO YOUR OWN LEVEL
------------------------------------------------------------------------
  This GOB is a small kit inside a demo room. Everything named scb* is
  the kit, and is what you copy. Everything named p56*, and scuba.jkl,
  is the demo room and stays here. The diving suit is neither: it is
  Gnarly's scubakatarn.3do, and your level brings its own copy of it.

  1. WHAT TO COPY

  Open P56.GOB with any GOB tool (ConMan, for one) and extract three
  files into your level's project folder, or add them to its GOB,
  keeping the folder names:

      cog\scbscuba.cog
      3do\scbtank.3do
      sound\scbbreth.wav

  Your level must ALREADY have the suit, from its author:

      3do\scubakatarn.3do
      mat\darker.mat        mat\divetank.mat      mat\bluesuede.mat
      mat\wetsuit.mat       mat\divereg.mat       mat\divelense.mat
      mat\cressifins.mat

  (kyhand.mat, the eighth material the suit names, is stock.) The
  scubakatarn.3do in P56.GOB is the author's file, byte for byte, and
  darker.mat and bluesuede.mat are the real Club OC files. The other
  five materials in P56.GOB -- divetank, wetsuit, divereg, divelense
  and cressifins -- are FLAT-COLOUR STAND-INS made for this demo. Do
  NOT copy them over the real ones.

  scbtank.3do is the tank cut off the suit's back. It uses three of
  the suit's materials, by the suit's names: bluesuede.mat,
  divetank.mat and darker.mat.

  2. THE TEMPLATE

  Exactly one new template is needed, for the tank. It is ONE line:

scbtank          _structure       model3d=scbtank.3do collide=1 size=0.040000 movesize=0.040000 thingflags=0x408

  Its parent, _structure, is stock. Put the line in the template list
  your editor reads (master.tpl for JED and ZED), or straight into the
  JKL's TEMPLATES section with "World templates" raised by one. In
  master.tpl, these two comment lines above it give the editor a name
  to show and a box to draw:

# DESC:   Scuba tank (scbscuba.cog)
# BBOX: -0.0078 -0.0077 -0.0275 0.0078 0.0077 0.0275

  collide=1 matters. _structure alone would give the tank collide=3,
  face collision, and then the player's Use ray has to land on a face
  of a mesh 0.055 tall and 0.016 across -- and it misses, without a
  word. With collide=1 the 0.04 sphere around the tank's middle is
  what gets pressed.

  The SUIT needs NO template. The cog puts it on the player with
  SetThingModel; the level only has to be able to load
  3do\scubakatarn.3do.

  3. PLACING THE TANK

  Place one thing of template scbtank. Its origin is the middle of the
  tank, and the tank is 0.055 tall, so standing upright on a floor it
  sits at z = floor + 0.0275. The demo leans it 6 degrees against a
  wall instead: pitch -6, z = floor + 0.0281, its middle 0.0093 out
  from the wall. The player presses Use on it from within about 0.2
  units, looking AT it -- it is small and low, so that means looking
  down.

  The tank stays where you put it. It is a locker, not a pickup: Use
  takes the gear, Use again hands it back.

  4. THE COG

  Add scbscuba.cog to the level's placed cogs, ONCE. It takes three
  values, in this order:

      tank       the thing number of the tank you placed
      capacity   seconds of air; 0 = unlimited (the default)
      suitmode   1 = the suit is worn whenever the tank is held
                     (the default)
                 0 = only while the player is in water
                 2 = only while he is submerged

  In a JKL that is one row of the COGS section. This is the demo's,
  where the tank is thing 1:

0:	scbscuba.cog	1	0.000000	1

  A 60 second tank whose suit goes on only in the water would be this
  instead:

0:	scbscuba.cog	1	60.000000	0

  5. WATER

  Nothing to mark. Any sector with the water flag (0x2) works; the cog
  finds out for itself whether the player is in it and whether he is
  under the surface. Drowning is the game's own, and it comes back the
  moment the gear is handed back or a finite tank runs dry.

  6. WHAT THE PLAYER GETS

  Use on the tank takes the gear; Use on it again hands it back. While
  he holds a tank with air in it he does not drown. The breathing loop
  starts after 2 seconds under water and stops when he surfaces. In
  suitmode 0 and 2 the suit comes off 2 seconds after it stops being
  wanted (get back in the water inside that and it stays on); handing
  the tank back takes it off at once, in every mode. The suit is a
  third-person model: he sees it on the external camera (F1).

  7. TEXT ON SCREEN

  With an unlimited tank: none. With a finite one, these five lines,
  once each per tank:

      Scuba tank: 75% air
      Scuba tank: 50% air
      Scuba tank: 25% air
      Scuba tank: 5% air
      Scuba tank empty!

  The cog also has a debug trace, every line of which starts with SCB.
  It sits behind "int dbg" in the cog's symbols, which is 0 in this
  package; set it to 1 to watch the cog think.

  8. LIMITS

  One tank and one instance of the cog per level. A second instance
  would be a second state machine editing the same player.

  Single-player is what has been tested. The cog is flags=0x240: it
  runs locally, is not synchronised, and edits only the local player.
  Read from the engine source and NOT tested: in a multiplayer game
  each machine would run its own copy for its own player, and the suit
  model, the air flag and the breathing would change on that machine
  only -- nothing is sent -- so other players would go on seeing the
  ordinary player model.

  Tested in OpenJKDF2 only. Retail JKDF2 has not run it.

  If you edit the JKL by hand, it must have room for what this adds:
  two entries in "World models" (scbtank.3do, and scubakatarn.3do if
  nothing else in the level uses it), the suit's seven materials in
  "World materials", one entry in "World sounds", and one each in
  "World templates", "World things", "World cogs" and "World scripts".
  An editor works these out when it saves.

WHAT IS IN THE GOB
------------------------------------------------------------------------
        88  episode.jk
      7848  jkl\scuba.jkl
     24845  cog\scbscuba.cog
     55304  3do\scbtank.3do
    105893  3do\scubakatarn.3do
    172172  mat\bluesuede.mat
      2188  mat\cressifins.mat
    131212  mat\darker.mat
      2188  mat\divelense.mat
      2188  mat\divereg.mat
      2188  mat\divetank.mat
      2188  mat\p56ceil.mat
      2188  mat\p56floor.mat
      2188  mat\p56pool.mat
      2188  mat\p56wall.mat
      2188  mat\wetsuit.mat
    225020  sound\scbbreth.wav

    742074  bytes in 17 entries

CREDITS
------------------------------------------------------------------------
  The diving suit, scubakatarn.3do, is by Gnarly, from his level Club
  OC. It is in this GOB exactly as he made it, under his name.
  darker.mat and bluesuede.mat are his textures from the same level.
  scbtank.3do is the tank cut off that suit's back. It, the cog, the
  demo room and the five stand-in textures were generated by
  tools/cogfactory in the openjkdf2_libretro tree. The breathing loop,
  scbbreth.wav, is vaderbreath.wav converted to 22050 Hz mono.

  The readme format is styled after SM Sith Lord's cog headers,
  because his are the ones everybody read.

========================================================================
