Dockscreens!

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Post Reply
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Dockscreens are a big part of the game, and can be powerful mods. In a dockscreen you can present all kinds of game data, perform complicated scripting, manage storyline and missions, and just about anything.

Dockscreens come in two forms- stand alone elements and child elements of other objects (stations). A dockscreen that is a child of another object cannot be called from other objects, I believe. I mostly use stand alone screens that can be opened from any object.

In objects, <Dockscreens> is used and any screens can be named. This format inherits the UNID of the object, and so does not require a UNID="" in the elements.

The stand alone dockscreen element is easy to learn, let's look at the basic structure:

Code: Select all

<DockScreen UNID="&dsMyFirstDockscreen;"
		name=				"Screen Title"
		backgroundID=		"none"
		>

	
	<Panes>
		<Default

			desc="You are viewing an empty screen."
				>
			
			<Actions>
				<Action name="Done" key="D" cancel="1">
                                 <Exit/>
				</Action>
			</Actions>
		</Default>
	</Panes>

</DockScreen>
This is the simplest of screens. It has few elements required.

<Dockscreen>

All stand alone dockscreens are wrapped in a <Dockscreen *> </Dockscreen> tag. Inside of <Dockscreen> you must place a UNID to identify the screen, and you can add some other attributes:
name = "[string or function]" this attribute places the title for the screen. You can put string in there, such as "My Title" or you can put a function in there- such as "=(objGetName gSource)" Functions must be prefixed with a = to be recognized, otherwise your title would end up "(myFunction)". Trust me when I say that that is an embarrassing title to see! (Almost as bad as a "nil" when the function doesn't work right!)

backgroundID="[UNID]" simply points to a graphic resource- you can use this to set the 600 x 400 left portion of the screen to anything you like there.

Obviously, in the sample above the default background is used. You can keep the default background by placing "none" as the backgroundID.

type="[string]" this attribute can be placed in <Dockscreen > to control the type of screen you are using. There are several types. The default type (or absence of type attribute) is just the background image or lack thereof, but for other screens you can set type to be:
type= "itemPicker" This gives you a item list screen which is used for many purposes in the game. The item list also requires that the backgroundID be set to backgroundID= "&rsItemListScreen;" for best presentation.

The Item list is also controlled by a child element <ListOptions *> which I will explain below.

type= "customPicker" can be used to display a list of options or data. The custom list also requires that the backgroundID be set to backgroundID= "&rsItemListScreen;" for best presentation.

The Custom list is also controlled by a child element <List> which I will explain below.


Child Elements List
Here is a short list of the elements I have found in screens:

<Panes>
<InitialPane>
<OnInit>
<ListOptions>
<List>
<Display> (new!)



<ListOptions>

ListOptions is a very small element that simply declared where the Item list is being drawn from- the object that has the items. It can also be used to filter for specific item types and modifiers. Here is an example:

Code: Select all

	<ListOptions
		dataFrom=	"station"
		list=		"*U"
		/>
dataFrom= "[string]" accepts 2 things that I have found- "station" or "player".

list= "[criteria]" accepts the standard search filters for items:

Code: Select all

			*	all categories
			a	armor
			d	device (weapon, shield, drive, etc.)
			f	fuel
			l	launcher weapon only
			m	missile
			r	reactor
			s	shields
			t	miscellaneous
			u	useful (armor coating, ROM, etc.)
			v	drive
			w	weapon (including launchers)
			I	is installed
			D	is damaged
			N	is not damaged
			S	is useable
			U	is not installed

	modifiers:
			+	must have this modifier
			-	must not have this modifier
You can control exactly what items are appearing in the item picker using these filter criteria in list= "[criteria]"


<List>

List is used by the customPicker type of screen to display a custom list instead of items. The list is created by scripting, and can be very dynamic.

The list prepared requires a certain format to be displayed as an item: (list [Title] (list [Image]) [Description])

On the other hand, you can also just put in (list "This" "Is" "A" "List")

Here is an example of making an itemPicker style list:

Code: Select all

<List>
(block (showList)
;this list will look like an item screen

	(setq showList (list

		(list "Title One" "NoImageForThis" "Description One")
		(list "Title Two" "NoImageHereEither" "Description Two")

	)) 

)
</List>
As you can see, List code can get complex quickly. But by using the scripting you can create information sets, control panels, navigation data, reports- anything you can imagine.

I am a big fan of the customPicker screen.

<OnInit>

The <OnInit> element is designed to allow some scripting to set up the screen- for instance, when you dock at a station <OnInit> is the element that determines of you have to see the radiation contamination screen or if you get to go to the default screen. This element is used to perform many kinds of preparation for a dockscreen data that allows the screen to adjust to the conditions it finds.

OnInit is the place to perform some code when you first open a dockscreen.

<InitialPane>

InitialPane functions much like OnInit, except that whatever code is run there must return the name of a pane to be viewed.

<Display>

This is a great new feature in the game added in version 0.99. This allows you to do some very simple design-level controlling of the Display section of the screen. The display is the 600 x 400 left area where the background and item list normally reside. I wouldn't recommend trying to use display and an item list screen together. Use the display element to layer images and text on top of the background.

This element is used in the Korolov screens to great effect.

<Display> takes two types of child elements:
<Text>
<Image>


...

<Panes>

Panes are the most important part of the screens- every dockscreen uses at least one pane.

Panes have named child elements such as <MyPane>, although I think adding the <Default> pane is important.

These named child elements are what you see and navigate between in dockscreens and take the attributes for description text (right panel) and some special pane features such as the text entry box and the number entry box.

Pane Child Elements have two very useful and critical child elements of thier own:
<Actions>
<Initialize>


<Initialize> takes code blocks and can be used to alter the description, get the data on something, and other uses.

<Actions> requires child elements <Action> and is dedicated to the control of the right panel menu options.


(more to come on these!)
Last edited by Periculi on Sun Aug 24, 2008 11:20 pm, edited 2 times in total.
User avatar
Betelgeuse
Fleet Officer
Fleet Officer
Posts: 1920
Joined: Sun Mar 05, 2006 6:31 am

in a customPicker screen what happens when you alter the list with lnkReplace (assuming you put the list in a global), like you wanted to change the name of something after the list was created without navigating away from the screen.
Crying is not a proper retort!
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Look at the Star Log I wrote- I update the list with the actions, but the screen must be updated, I thought, so that's how I did it.

Anytime you move or click on the list the screen is updated, but using lnkReplace directly on the source list in an action isn't something I have tried. It seems like you want to do something fancy without updating the screen, which you would need to try out and let me know.

I think it would work, actually.
User avatar
Betelgeuse
Fleet Officer
Fleet Officer
Posts: 1920
Joined: Sun Mar 05, 2006 6:31 am

just tested it and it works great 8)
lnkRemove
lnkReplace
lnkAppend

all work fine

so now we don't have to navigate away from the screen to change it any way we want

a helper function like lnkInsert would be nice for someone to make but that is getting more into script help
Crying is not a proper retort!
User avatar
Betelgeuse
Fleet Officer
Fleet Officer
Posts: 1920
Joined: Sun Mar 05, 2006 6:31 am

hmm a few more points on custom picker

does scrGetItem work to get the list of the thing selected or should we use the one deprecated function (why was that deprecated)?

you can have as many elements in that list you want so you can store things on the list that are hidden to the player
Crying is not a proper retort!
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

(scrGetListEntry gScreen) is how you get the currently selected list item.

(setq theInfo (item (scrGetListEntry gScreen) 3)) item 3 and up can be hidden values, yes- or call them "additional" items if you prefer.
User avatar
Betelgeuse
Fleet Officer
Fleet Officer
Posts: 1920
Joined: Sun Mar 05, 2006 6:31 am

is there a way of changing where the cursor is?

The dockscreen keeps on crashing if you do an action and the cursor isn't on an item.
Crying is not a proper retort!
F50
Fleet Officer
Fleet Officer
Posts: 1004
Joined: Sat Mar 11, 2006 5:25 pm

Code: Select all

<Action name="Done" key="D" default="1" cancel="1"> 
how about default="1"?
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

I haven't figured out that one yet. :shock:

I never use it, and don't know what it does. In fact, there are a lot of the action attributes that I don't understand and can't find a way to decipher. Maybe George will explain some of the action attributes one day.

I am guessing that it may be connected to the action enabling. Everywhere I have seen it used, it is connected to an action that can be disabled if certain conditions aren't met. But it doesn't seem to be required for anything that I have found. It never seems to have a value other than "1" and so must not be connected to positioning the action on the menu... *clueless shrug*

I should take default="1" out of my sample, I left it there by mistake.
User avatar
Betelgeuse
Fleet Officer
Fleet Officer
Posts: 1920
Joined: Sun Mar 05, 2006 6:31 am

default="1" means when you hit enter it activates
cancel="1" means when you hit Esc it activates

I use that feature all the time.
Crying is not a proper retort!
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Oh, that's nice to know! Thanks, Betel.
User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

I've been banging my head against a wall trying to get a custom station to sell specific things.....and it was here all along! :roll:

This is a big help! Thanks ;)

EDIT : I've only used Dockscreens inside a <Station> element. How do I go about telling Trans to load a stand-alone Dockscreen outside a station?

You said:
I mostly use stand alone screens that can be opened from any object.
How do I open a screen from the player's ship? As in I want to display a new version of the inventory (or a list of just illegal goods the player has for instance)
Post Reply