Discuss this page on this page's [[Usable objects Talk Page|Talk Page]].

==== Creating Usable Objects for Total n00bs ====

This exercise has been brought to you by [[community:user:ptbptb|a total n00b]] to Transcendence modding.  Check out [[replacing content|the first one in the series]] for tips I might not be covering here again.

==== Step One: Decide what to do ====

It's probably not a good idea to go overboard here.  So what you need is something that you're sure will be 'doable', preferably not too hard, and would come in handy in the game.  My idea is for a ROM - "Jane's Interactive Guide to Spaceships".  It's a one-shot trial-offer ROM that will identify any one non-alien, non-illegal unidentified item.  OK, this is basically very similar to the [[http://xelerus.de/index.php?s=mod&id=702|barcode scanner]] extension, but I like the idea of a one-shot identifier (it reminds me of 'scrolls of identification' ;-) )  To make this challenging I won't be looking at the barcode scanner code.  I will be looking at the [[http://xelerus.de/index.php?s=mod&id=383|other mods]] and possibly the [[modding:TransData|Transcendence Source]] though.

==== Step Two: Create a file ====

We'll go with the obvious JanesROM.xml and create a blank .xml file with the standard start/end bits.

<code xml>
<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
   <!ENTITY UNIDJanesROM "0xD0000060">
   <!ENTITY itJanesROM   "0xD0000061">
]>
<TranscendenceExtension UNID="&UNIDJanesROM;" version="1.0" name="Jane's Interactive Guide to Spaceships" credits="Total n00b">

   <!-- Jane's Interactive Guide to Spaceships -->

</TranscendenceExtension>
</code>

If you read the last tutorial then the only really new thing here is the 'it' prefix (for item) instead of the 'st' prefix (for station) we used last time.  We'll be using that in step three.

==== Step Three: Add item details ====

Looking at the [[http://xelerus.de/index.php?s=mod&id=383|Huari Citizen ROM]] mod it's clear that this time we are dealing with the [[modding:xml:ItemType|<ItemType>]] element while last time we were working with the [[modding:xml:StationType|<StationType>]] element.  Most of the details can be filled in without thinking about them much. Indeed it's pretty much copied straight out of the xml file I've consulted. (Thanks Darth Saber!)

In the traditional way (since when?) I'm also including code so that typing (romME) in the debug console will produce a copy to test.

<code xml>
<ItemType UNID="&itJanesROM;"
		name= "Jane's Interactive Guide to Spaceships"
		level= "1"
		value= "50"
		mass= "1"
		frequency= "common"
                modifiers= "Consumable; Info"
		description= 
"This is a trial offer ROM which will run only once, after which its database is wiped. It can identify one object or device (that is not alien or illegal)."
		>

	<Image imageID="&rsItems1;" imageX="192" imageY="96" imageWidth="96" imageHeight="96"/>

	<Invoke>

;... stuff goes here ...

	</Invoke>
</ItemType>

<Globals>
   (setq romME (lambda Nil
      (objAddItem gPlayerShip (itmCreate &itJanesROM; 1))
   ))
</Globals>
</code>

So far so good, but it doesn't actually do anything (that's what the inside of the [[xml:invoke|<invoke>]] element is for).  Give it a try anyway and you can see one problem to fix - it is already identified.  I prefer ROMs to be a surprise when you first buy them.  Looking inside [[modding:TransData|Transcendence Source]] I find UsefulItems.xml   That gives us this useful line as an ItemType attribute //			unknownType="&itUnknownROM;"//  We can also nick a chunk of the code inside the Invoke element as well.

<code xml>    <ItemType UNID="&itJanesROM;"
        name= "Jane's Interactive Guide to Spaceships"
        level= "1"
        value= "50"
        mass= "1"
        frequency= "common"
        unknownType= "&itUnknownROM;"
        modifiers= "Consumable; Info"
        description= 
"This is a trial offer ROM which will run only once, after which its database is wiped. It can identify one object or device (that is not alien or illegal)."
        >

        <Image imageID="&rsItems1;" imageX="192" imageY="96" imageWidth="96" imageHeight="96"/>

        <Invoke>
            (block Nil

                ; Identify the item
                (itmSetKnown gItem)

                ; Remove ROM
                (objRemoveItem gSource gItem 1)
            )
        </Invoke>
    </ItemType>

    <Globals>
        (setq romME (lambda Nil
            (objAddItem gPlayerShip (itmCreate &itJanesROM; 1))
        ))
    </Globals>   </code>

So, what have we got now?  It's an unknown ROM when first encountered, if you use it it disappears and the next time you see one it is identified.  So far so good.  We haven't got to the actual aim of the game yet, though.

==== Step four: Make it do stuff ====

When it is used (invoked) we want it to 
  * Display all items on your ship (installed, or uninstalled) and prompt you to select one.
  * Either identify the item selected, or (if it alien or illegal) give an error message.

=== Display list and select an item ===

I had a look around and there are other usable items that do this, like [[http://xelerus.de/index.php?s=mod&id=741|The Almighty Wrench!]] and the [[http://xelerus.de/index.php?s=mod&id=650|Stasis Pod]] (along with a bunch of others, I expect).  Anyway the key ingredient is a [[xml:DockScreen|<DockScreen>]] element.  There's a couple of other things we also need to add.  

<code>      useScreen= "&dsUseWrench;"</code>
A new attribute needed in the ItemType element.

<code xml>  <!ENTITY dsUseWrench      "0xD0030003"></code>
An extra UNID for the DockScreen.

And here's the one from AlmightyWrench (with a whole bunch o'stuff snipped out).

<code xml>  <!-- The dockscreen for our speciality wrench: -->
  <DockScreen UNID="&dsUseWrench;"
      name=       "Ship's Cargo Hold"
      type=       "itemPicker"
      backgroundID=   "&rsItemListScreen;"
      >

    <ListOptions
      dataFrom= "player"
      list=   "UD~a*"
      />

    <Panes>
      <Default
          desc= "What item do you wish to repair?">

        <Initialize>

;... skip bits ...

        </Initialize>

        <Actions>
          <Action name="Repair this item" imageID="&rsItemListScreen;" imageIndex="1" default="1" key="R">

;... skip bits ...

          </Action>
          <Action name="Cancel" imageID="&rsItemListScreen;" imageIndex="0" cancel="1" key="C">
            <Exit/>
          </Action>
        </Actions>
      </Default>
    </Panes>
  </DockScreen></code>

At this point: Whoops! We don't need the <Invoke> element after all.  The code for stuff happening actually goes inside the DockScreen element. (Well, live and learn)

Right, onwards and upwards.  Lets put together what we've got so far.

<code xml><?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
   <!ENTITY UNIDJanesROM "0xD0000060">
   <!ENTITY itJanesROM   "0xD0000061">
   <!ENTITY dsUseJanes   "0xD0000062">
]>
<TranscendenceExtension UNID="&UNIDJanesROM;" version="1.0" name="Jane's Interactive Guide to Spaceships" credits="Total n00b">

   <!-- Jane's Interactive Guide to Spaceships -->

    <ItemType UNID="&itJanesROM;"
        name= "Jane's Interactive Guide to Spaceships"
        level= "1"
        value= "50"
        mass= "1"
        frequency= "common"
        unknownType= "&itUnknownROM;"
        modifiers= "Consumable; Info"
        useScreen= "&dsUseJanes;"
        description= 
"This is a trial offer ROM which will run only once, after which its database is wiped. It can identify one object or device (that is not alien or illegal)."
        >
        <Image imageID="&rsItems1;" imageX="192" imageY="96" imageWidth="96" imageHeight="96"/>

    </ItemType>

    <!-- The dockscreen for the ROM user interface: -->
    <DockScreen UNID="&dsUseJanes;"
      name=       "Ship's Cargo Hold"
      type=       "itemPicker"
      backgroundID=   "&rsItemListScreen;"
      >
 
    <ListOptions
      dataFrom= "player"
      list=   "*"
      />

    <Panes>
      <Default
          desc= "What item do you wish to identify?">

        <Actions>
          <Action name="Identify this item" imageID="&rsItemListScreen;" imageIndex="1" default="1" key="I">
            (block Nil

;... stuff goes here ...

                ; Identify the Jane's ROM we have just used.
                (itmSetKnown gItem)

                ; Remove Jane's ROM
                (objRemoveItem gSource gItem 1)
            )
          </Action>
          <Action name="Cancel" imageID="&rsItemListScreen;" imageIndex="0" cancel="1" key="C">
            <Exit/>
          </Action>
        </Actions>
      </Default>
    </Panes>
    </DockScreen>
    <Globals>
        (setq romME (lambda Nil
            (objAddItem gPlayerShip (itmCreate &itJanesROM; 1))
        ))
    </Globals>   
</TranscendenceExtension></code>

=== (Finally) Identify item ===

OK, we're nearly there.  A quick look at the [[functions:item functions]] finds [[functions:itmSetKnown]] and [[functions:itmIsKnown]], both of which are going to come in useful.