Tutorial : Create a custom menu and Custom Interface Key (WIP)

[LV]

LV's Terran Conflict Script Index

Tutorial Adding A Custom Menu

____________

*******note for other contributors*******

link http://code.google.com/p/x3tcscripts/

Code: Select all

it would be good here people if the code your c+ping from could be uploaded as a separate script for users to use or look at in more detail (remember many new scripters don't know where all the command we take for granted are)

uploading a script is simple using the google upload site i've imperialised for tc

just log in with
lordvader@ikillclowns.com
egosoftmods 

takes about 20 seconds to upload a script ;)

___________

First you can install this download to your x3 folder which contains the tutorial scripts

[ external image ]

zip

Cycrow Installer Version

[ external image ]





Once installed you need the 8800-L044 t file in your t directory

[ external image ]

Below is the t file text

Code: Select all

<language id="44"> // english (49 is german)
−
<page id="2008" title="Script Object Commands" descr="0">
<t id="1309">A_LV_TUTORIAL_MENU</t>
</page> \\ creates the command shown lower in the "Custom" interface
−
<page id="2010" title="Script Cmd Names" descr="Long version of commandos. These are the commandos assigned to ships using the commandconsole. Page 2010 and 2011 belong together and hold short and long versions of the same commands">
<t id="1309">Open Tutorial Interface</t>
</page>
−
<page id="2011" title="Script Cmd Shorts" descr="Short version of commandos. These are the commandos assigned to ships using the commandconsole. Page 2010 and 2011 belong together and hold short and long versions of the same commands">
<t id="1309">OTI</t>
</page>
−
<page descr="" id="8800" title="Tutorials">
<t id="1">\033GChoose a station or ship\033X</t>
\\makes the text ingame show as green
<t id="2">You chose \033R%s\033X</t>
\\shown in the games rss feed ticker bottom left of screen
<t id="3">Play a sound</t>
<t id="4">Enter sound number 900-1000</t>
<t id="5">Open another menu</t>
<t id="6">Option 1</t>
<t id="7">Option 2</t>
<t id="8">Option 3</t>
<t id="9">Option 4</t>
<t id="10">Option 5</t>
<t id="11">Tutorial Interface Main Menu</t>
<t id="12">Tutorial Interface 1st Menu</t>
<t id="13">Tutorial Interface 2nd Menu</t>
<t id="14">Show Some Text In The RRS Feed</t>
<t id="15">This is tutorial text by \033GLV\033X</t>
</page>
</language>

The highlighted 2 files will also be in your scripts directory if you have installed correctly.

[ external image ]

Once ingame go into your script editor will have the 2 scripts near the bottom of the list

[ external image ]

Code: Select all

Script setup.lv.tutorials
Version: 0
for Script Engine Version: 41
Description
Tutorial scripts for TC scripters
Arguments
Source Text

001   load text: id=8800
002   * loads youtr t file
003   $ware = Cargo Lifesupport System
004   
005   add ship custom command: id=1309
006   * loads the text from your t file to set up a comand in the interface
007   set script command upgrade: command=A_LV_TUTORIAL_MENU  upgrade=[TRUE]
008   * upgrade = TRUE means command shows by default
009   
010   *set script command upgrade: command=A_LV_TUTORIAL_MENU  upgrade=$ware
011   * upgrade = ware means unless the ship has the ware installed the command is off
012   
013   
014   global script map: set: key=A_LV_TUTORIAL_MENU, class=Moveable Ship, race=Player, script='tutorial.lv.main', prio=0
015   * this adds the command to all your ships and calls the script that the comm uses
016   * command will now show in custom interface.   
017   return null

Once installed you will now have the command in your "Custom Menu"

[ external image ]

[ external image ]


The setup script is what binds the new command above from the t file.


[ external image ]

Which then opens this menu

[ external image ]

Choose the "open another menu" option for this

[ external image ]



When you select the command

this is the script called which we set up into the initail setup.tutorial script above

global script map: set: key=A_LV_TUTORIAL_MENU, class=Moveable Ship, race=Player, script='tutorial.lv.main', prio=0

Code: Select all

Script tutorial.lv.main
Version: 0
for Script Engine Version: 41
Description
Description
Arguments

Source Text

001   $anull = null
002   
003   $a = 'a'
004   $b = 'b'
005   $c = 'c'
006   $d = 'd'
007   $e = 'e'
008   $f = 'f'
009   
010   
011   $text = sprintf: pageid=8800 textid=11, null, null, null, null, null
012   $menu =  create custom menu array: heading=$text
013   
014   $text = sprintf: pageid=8800 textid=1, null, null, null, null, null
015   add custom menu item to array $menu: text=$text returnvalue=$a
016   
017   $text = sprintf: pageid=8800 textid=3, null, null, null, null, null
018   add custom menu item to array $menu: text=$text returnvalue=$b
019   
020   $text = sprintf: pageid=8800 textid=5, null, null, null, null, null
021   add custom menu item to array $menu: text=$text returnvalue=$c
022   
023   add custom menu item to array $menu: text='Tell Me What Ship I'm In' returnvalue=$d
024   
025   $text = sprintf: pageid=8800 textid=14, null, null, null, null, null
026   add custom menu item to array $menu: text=$text returnvalue=$e
027   
028   $text = sprintf: pageid=8800 textid=11, null, null, null, null, null
029   
030   add custom menu item to array $menu: text='Monitor For Users Closing Menu Accidently' returnvalue=$f
031   
032   loop:
033 @ = wait 1 ms
034   $return =  open custom menu: title=$menu description=$text option array=$menu
035   
036   
037   if $return == $a
038   |$input = [THIS] -> get user input: type=Var/Ship/Station, title='Choose a station or ship'
039   |$text = sprintf: pageid=8800 textid=2, $input, null, null, null, null
040   |display subtitle text: text=$text duration=3000 ms
041   else if $return == $b
042   |$text = sprintf: pageid=8800 textid=4, null, null, null, null, null
043   |$menu =  create custom menu array
044   |add custom menu item to array $menu: text=$text returnvalue='sound'
045   |$sound =  open custom menu: title=$menu description='try 928' option array=$menu
046   |$input = [THIS] -> get user input: type=Var/Number, title=$text
047   |play sample $input
048   else if $return == $c
049   |$text = sprintf: pageid=8800 textid=12, $anull, null, null, null, null
050   |$menu.1 =  create custom menu array: heading=$text
051   |$text = sprintf: pageid=8800 textid=6, $anull, null, null, null, null
052   |add custom menu item to array $menu.1: text=$text returnvalue=$f
053   |$text = sprintf: pageid=8800 textid=7, $anull, null, null, null, null
054   |add custom menu item to array $menu.1: text=$text returnvalue=$f
055   |$text = sprintf: pageid=8800 textid=8, $anull, null, null, null, null
056   |add custom menu item to array $menu.1: text=$text returnvalue=$f
057   |$text = sprintf: pageid=8800 textid=9, $anull, null, null, null, null
058   |add custom menu item to array $menu.1: text=$text returnvalue=$f
059   |$return1 =  open custom menu: title=$menu.1 description='Tutorial' option array=$menu.1
060   else if $return == $d
061   |$pship =  get player ship
062   |$text = 'You are currently flying a ' + $pship
063   |display subtitle text: text=$text duration=3000 ms
064   else if $return == $e
065   |$text = sprintf: pageid=8800 textid=15, $anull, null, null, null, null
066   |display subtitle text: text=$text duration=3000 ms
067   else if $return == $f
068   |display subtitle text: text='Next time the menu appears press del key' duration=3000 ms
069 @ |= wait 4000 ms
070   |goto label loop
071   else if $return == -1
072   * if del is pressed the rturn value is -1
073   * make a loop to stop this
074 @ |= wait 4000 ms
075   |goto label loop
076   end
077   
078   
079   
080   
081   return null

___
within the Tutorial scripts you can now also see how to check if a user closes a menu //


LV's Terran Conflict Script Index

[Draslin]

Edit LV good thread, merged

I'm posting a general description of where the menu elements appear and how they will behave.


Menus

There are a few ways to create a menu. You can create a menu, or create a menu and specify a heading, and one other I think (at work, will confirm later). You should always use the second option if you plan to use headings.

Here's why.

If you create a menu without a heading and then open it later, the title you open that menu with also becomes a heading. The title appears at the top of a menu above the info lines, but it would also appear as a heading beneath the info lines.

You can specify a heading after the fact, but it must be immediately after the fact. If you do anything else after creating your menu without the heading, it won't work. (Thanks Cycrow)

You can't specify a heading later in the script it, you'll only end up with a second heading.

Info line

The info line will appear at the top of your menu. If the text string is wider than the menu it will wrap but this line will not wrap and continue on the next line. Instead scroll arrows will appear to the right of it that allow you to scroll downward to see the rest of the text. It will take one line of space. Very awkward.

Adding additional info lines appear as expected beneath the last info line. You could liken this to an End of Line or return. Each line of your info area will need to be a separate "add info line".

There is only one info line section in any menu. You can add info lines at the bottom of a list of menu items and it will still be placed at the top of the menu with any other info lines.

Heading

Headings follow the info lines and there can be more than one heading in a menu. Headings need to be placed logically, unlike info lines, they must be placed in the order you want them to appear.

Items

Items could also be called options or choices. These lines will give the user a menu item to select which then gives feedback to a script. Items need to follow headings.

Notes

You can put multiple headings and items, but you need to do so sequentially to make sure they show up properly.

For example.

Add heading 'Commands'
Add heading 'Cheats'
Add item 'Remove Command'
Add item 'Add Command'
Add item 'Give credits'
Add item 'Jump to'
Add item 'Kill target'

Will come back as...

Commands
Cheats
Remove Command
Add Command
Give credits
Jump to
Kill target


Rather than the intended...


Commands
Remove Command
Add Command
Cheats
Give credits
Jump to
Kill target

My examples aren't very good I know. But hopefully the information will be useful for those trying to get started with the custom menu's.

And one Neat Trick I just learned.

Menu items can be pressed into service as pseudo info lines.

By making the return value on a menu item NULL, it becomes unselectable.

As an example; if you had a menu that loaded a list of specific ships, say all M5 ships in a specified wing and there is a chance that their might not be any M5's in that wing. In which case your menu would be empty. You could when that condition is met (no M5's) add a menu item with a null return value that says "No M5 ships in this wing."

This prevents you from continuing while making it clear why and keeping that menu on screen. It won't close out because the NULL value apparently doesn't count. Which leaves the user free to choose another option if there are any present.

If you hit escape it will however return NULL, so make sure you put in a check to convert NULL to -1.

[Cycrow]

Id just like to confirm a few things about the menu system

You can't specify a heading after creating the menu to fix it, you'll only end up with a second heading.

you can add a heading after creating the menu, as long as its the first thing you do.

ie,

Code: Select all

$menu = create menu array
add heading to menu $menu...

one other thing you can do with custom menus. Is the menu array is simply just a normal array, so this can be used to display a list of ships quite simply

Code: Select all

$ships = get ship array: moveable ship race=Player
$ret = open custom menu: title=, desc=, array=$ships

and this will list all ships in the array and return its position, so if you select the first one, $ret will be 0 so you can get the item after by doing

Code: Select all

if $ret != -1
  $ship = $ships[$ret]
end

$ret is always -1 when esc is pressed so make sure you dont use that as any of your return values. Also, using 0 as a return value wont work either, as the menu system sees that as null instead

[Draslin]

Are you sure about the heading? I'm not doubting it, partly because I'm at work, partly because I've been using Hydrocodine due to wisdom teeth issues, but I'd swear I had problems doing that last night.

I'm going to experiment a bit more when I get home but I was pretty sure the behavior was wonky when you actually opened the menu later, the description if you entered in a text string of your own would then be both the heading and the title of the custom menu at the top. This was the behavior I was trying to avoid. If I made the title the menu array it would put the heading instead for both. What I was trying to do was get a title and something different for the heading.

And if I'm not making myself clear, well... Hydrocodine WoooHOOOO!!!!.



But seriously I'll take some screen shots at home to demonstrate the problem if it actually exists when I take a look again.

[Graxster]

Thanks a bunch, LV. You're awesome, as always! I was just gonna look for a tutorial on this... no kidding! Been working on a script that needs to be available from the ship command console. Looks like this will do the trick!

-Grax

[Cycrow]

i could tell you exactly how the custom menus worked

btw, when i said the heading must be added first, i really meant first, this is before any info lines and such too, and that includes the create menu with info line.


internally,

Code: Select all

$menu = create menu array
add custom menu heading to array, $menu title="heading"

is identical to

Code: Select all

$menu = create men array with heading = "heading"

custom menus are just arrays.

the $menu = create menu array, is actually the same as, $menu = array alloc: size = 0

it just makes reading the scripts easier

[Litcube]

Here's another tip:

Code: Select all

set ship command preload script: command= BE_AWESOME script= Menu.BeAwesome 

Code: Select all

global script map: set: key= BE_AWESOME, class=Ship, race=Player, script=Cmd.BeAwesome, prio=0

The preload command is very useful for those command scripts where you want to initiate a menu before launching the action.

Whenever the COMMAND is called, the script specified using the PRELOAD code line will launch *prior* to launching the regular global map key. What's unique about this, is that you can use the pre-loaded script to return arguments to the regularly scheduled script so that there's a seamless interface between menu and script command. Use this command at the end of your preload script (Menu.BeAwesome) to set the variables of the command script:

Code: Select all

 $BeAwesomeMenuItems = create new array, arguments=menu choices1, 2, 3, etc.

Code: Select all

 return $BeAwesomeMenuItems

At this point, your Cmd.BeAwesome script (notice the difference in names and how they're mapped above), will launch, using the data that was returned from the Preload script as its arguments effectively "skipping" the user argument input stage in the CMD script.

Just another way to keep things clean and tidy, and to seperate the Data from the Logic, like most good programmers should.

[Draslin]

btw, when i said the heading must be added first, i really meant first, this is before any info lines and such too, and that includes the create menu with info line.

I'll bet that was the problem. I was messing with info lines and what not too so I probably had something ahead of the heading. Its amounts to no difference though as you point out. Which is what I was thinking too.

[Malakie]

STICKY!

STICKY!!

STICKY!!!


SSSTTTTIIIIICCCCKKKKYYYY!!!!!!!!

[Draslin]

I believe its already referenced in the sticky at the top of the forum, something about tutorials and resources, though for some reason this comes up when you click on the scripting editor tutorial and the scripting editor tutorial comes up when you click on the custom menu tutorial.

[Graxster]

I need help, lol. I just can't seem to wrap my head around all the id numbers and how they work. Here's what I'm trying to do:

Add a Command and add a command to the Special ship menu. I get the part about having a setup file that says load text: id= (number)

When trying to add "set script command upgrade:", my COMMAND signal thingy isn't going to be listed, so how do I get that in the game? Also, the numbers are confusing. Look at this from one of Cycrow's scripts:

Code: Select all

<page id="2008">
<t id="1300">COMMAND_CYCROW_SHIPCHEAT</t>
<t id="1114">COMMAND_CYCROW_STATIONCHEAT</t>

Where do you get "page id 2008" number from? And why t id's 1300 and 1114. None of those correspond to any command slots or text file/page id's listed in the main forum sticky.

So far what I can understand is choosing an unused Page ID (8000 in my case) and an unused command slot in the Special Command Software (530 in my case). Help would be appreciated.

-Grax

Edit: Is Page ID 2008 for COMMANDS? In most of these t files the internal Page ID is the same number as the Text ID... (except when it's 9999). I'm guessing that each command has an id, so we need to select unused id's (hence Cycrow's 1300 and 1114). If so, how do I get those ids and know which are available?

[Cycrow]

you could try looking here

http://cycrow.thexuniverse.us/scripts/h ... mmand.html


its from X3R, but the process is the same.


but basically, you dont add new commands (well you can, but its first best to use the ones that are available)

the game comes with free command slots that you can use. You can check the community scripts sticky for the list of these command slots and which ones are currently used.

internally in the game, each of these command slots have a certain ID, that id is what is used in your text files.

the page 2008, 2010 and 2011 are the pages that the game looks at for the text.

you cant add text to you own page, they must be in the correct page ids.

ignore the id 1300, as this is a custom command that must be added to the game seperatly.

but the other one, 1114, is one of the built in commands.

the first 2 numbers is the type of command it is, 11 = station command. then 14 is the id.


as u've already selected the slot to use (530) you just need to put it in the correct page.

page 2008 is the command name, this is how it appears in the script editor, so when you are writing scripts and goto the var/command, it will display this text, without this it will use the standard name instead

page 2010 is the Text for the command, and this is what is displayed to the players in the command console

2011 is whats known as the short name, this is also displayed to the player in the command console, the short name is the one on the right in brackets


if you are just adding text for something to use in your script, ie log messages, etc. Then you use your own page and use the read text commands to get that.

however, when you want to use something built in like the wares and command slots, they must go in the correct page id

[Graxster]

Ok, I think I get it now, thanks.

Code: Select all

<?xml version="1.0" encoding="UTF-8" ?>
<language id="44">

<page id="2010">
<t id="530">Do a Test...</t>
</page>
<page id="2011">
<t id="530">Test</t>
</page>
<page id="2008">
 <t id="530">COMMAND_GRAX_TEST</t>
</page>

Does that look correct for the t file?

I have one more question. When calling a script from the command menu (in my case, Special menu), what does the script engine assign as a value for the ship whose command menu it came from? ie: I have Ship1 (non-playership that's accessing the command menu) and Ship2 that Ship1 is going to act upon (fly to, attack, resupply or whatever).

In my test script before I had a menu option, I used variables for Ship1 and Ship2. So for example, $speed1 = $Ship1 -> get current speed, $speed2 = $ship2 -> get current speed. Instead of using $Ship1 now, do I just use $speed1 = [THIS] -> Get current speed?

[Cycrow]

the ship that the command is run on, ie the ship that command console you went to, will be [THIS]

then if you wanted to select a target ship, you can set an argument for var/ship in the command.

then when the command is run, you will be asked to select that ship

so what ever varible you assign to that argument, will be your second ship

[Graxster]

Awesome, thanks! I'm having a problem with the last detail now. I have a setup file with "set command upgrade" that requires Special Command Software - that works fine. However, when you add a variable $ware such as in LV's example (cargo life support) that only looks for upgrades, yes? ie: Triplex scanner, cargo life support, mineral scanner, etc. So if, for example, I wanted the command on the Special menu to be unavailable if you don't have High Energy Plasma Throwers installed, I can't use it, right?

Any way to have the menu command unavailable for missing cargo items?

-Grax

[Cycrow]

there is another commandavailable you can use.

set commad upgrade, but it has an additional argument for a for a script

That script is used as a check script, so its called when ever your command is about to display the command. You can then tell the command console that the command is disabled if you are missing something.

as its a script, it can check for anything you like

there are a few constants for the return values. Return the disabled one if you want it disabled, or one of the other flags depending on what you want it to do.

you can return mulitiple flags to change the behaviour of the commands as well.

the first argument of this script must be the ship, [THIS] doesn't work on these scripts as they are run globally, so usualyl you set

$ship var/ship as the first arguments

then you can just check $ship for what ever ware/weapons, or anything else you want to check for

[Graxster]

Thanks! That worked perfectly.

-Grax

[JumperBR]

Hi,
Im working on a new project and I could use a custom menu... is there any tutorial on creating a menu?

edit: nvm, just found it...

[TSM]

I was about to say LV did this

http://forum.egosoft.com/viewtopic.php? ... t=#2591350

[jlehtone]

is there any tutorial on ..?

edit: nvm, just found it...

In a perfect world there would be a sticky helping to find/request/propose tutorials and resources. Wait, there is.