Pale Blue Light, a full tutorial for Transcendence modders.

Post about your finished mods here.
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm


A while ago, I announced that I would be working on a mod that creates a small, stand alone adventure. In my opinion, such a mod was sorely needed, as it would allow new modders to look through it and gain a basic but well rounded understanding of TLisp, removing - or at least weakening - the difficulty of transitioning from basic mods like additional playerships and weapons to more complex things. At long last, the mod is complete, and ready for download.

Image
Features:
- One mission, given by a single station to destroy another station. -

- Two systems, one constructed manually and the other procedurally generated with an element added in. -

- 2 custom stations, one custom AI ship, one custom playership -

- Basic topology -

- Comments throughout the code -

Link to download Pale Blue Light

Last edited by JohnBWatson on Tue Jan 26, 2016 9:10 pm, edited 5 times in total.
User avatar
Song
Fleet Admiral
Fleet Admiral
Posts: 2801
Joined: Mon Aug 17, 2009 4:27 am

Nicely done. I'll definitely be looking at this later in the year when I've got the time to do some learning. :)
Mischievous local moderator. She/Her pronouns.
User avatar
digdug
Fleet Admiral
Fleet Admiral
Posts: 2620
Joined: Mon Oct 29, 2007 9:23 pm
Location: Decoding hieroglyphics on Tan-Ru-Dorem

very nice !
I'll have a look too ! :)
User avatar
catfighter
Militia Commander
Militia Commander
Posts: 466
Joined: Fri Nov 08, 2013 5:17 am
Location: Laughing manically amidst the wreckage of the Iocrym fleet.

Sweet! :) It'll be a while before I get to look into it, but congrats on completing it!
Behold my avatar, one of the few ships to be drawn out pixel by pixel in the dreaded... Microsoft Paint!

Day 31: "I have successfully completed my time reversal experiment! Muahahaha!!!"
Day 30: "I might have run into a little problem here."
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm

Thanks, people. As always, feel free to suggest improvements/point out flaws. I'll fix anything that needs fixing ASAP once it's pointed out.
User avatar
Xephyr
Militia Captain
Militia Captain
Posts: 857
Joined: Fri Dec 14, 2007 1:52 am
Location: Orion Arm, Milky Way
Contact:

Pretty good all around, though I'd like to see more than two systems in the stargate topology, since even basic topology seems pretty confusing to newcomers.

I'd suggest adding a gate that goes to endgame in the second system.
Project Renegade (Beta) : "The Poor Man's Corporate Command!"
Real programmers count from 0. And sometimes I do, too.
relanat
Militia Captain
Militia Captain
Posts: 941
Joined: Tue Nov 05, 2013 9:56 am

Excellent. Thanks for doing this. I learnt more in the 30 minutes I spent looking at this than from about 10 hours crawling through more advanced code. Nicely laid out and well explained. My only suggestion would be to put even more comments in.
Stupid code. Do what I want, not what I typed in!
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm

relanat wrote:Excellent. Thanks for doing this. I learnt more in the 30 minutes I spent looking at this than from about 10 hours crawling through more advanced code. Nicely laid out and well explained. My only suggestion would be to put even more comments in.
That can be done easily enough. Anything you'd like me to focus on?

Xephyr wrote:Pretty good all around, though I'd like to see more than two systems in the stargate topology, since even basic topology seems pretty confusing to newcomers.

I'd suggest adding a gate that goes to endgame in the second system.
I feel like adding more connections is adequately covered in the main Transcendence decompile once the basic stuff is known. However, this is only my opinion. If there is a simple means of doing this, it might be worthwhile to include a folder including the code for adding various features to the mod, that being one of them, submitted by various forum users.

In the next release I'll add a tutorial on how to run Transdata's /decompile, for anyone who finds the tutorial but doesn't have the source code yet.
relanat
Militia Captain
Militia Captain
Posts: 941
Joined: Tue Nov 05, 2013 9:56 am

JohnBWatson wrote:That can be done easily enough. Anything you'd like me to focus on?
Well.... since you asked. :) Commence rambling thoughts.

Very basic stuff. Using BlueLight.xml as an example.

Within <AdventureDesc

startingShipCriteria=
It looks like any ship with an attribute of D0110000_Playership will work here. Is this the only option? Can it be a UNID instead. Can this adventure look at the 3 standard starter ships in the base game?

startingSystem=
"SE" is a nodeID (as per ExtSystemMap.xml) Can it be anything else? Can you start in the middle of a topology?

startingPos=
What is "Start"? What other options are there?

<Text id="description" which I think means it will print this text in the upper right of the screen. Can anything else be put on the screen?
I'm not sure why you need (cat here given that it is only one lot of text.
And what does the {/rtf do?

What is <GetGlobalAchievements> and what does intGetGlobalAchievements do?

Etc, etc.

In the code itself things like gamSetCrawlImage and gamSetCrawlText are fairly obvious but what is /n/n, %name%, and aEpitaph and how are they used?
Why do you need plyComposeString in <OnGameEnd> and not <OnGameStart>?
What makes aBestEnemiesDestroyed different from aEnemiesDestroyed? And what does 0x04 and 0x02 do?

Like I said, VERY basic stuff.


I use the xelerus functionlist a lot and it is very helpful but it tends to be a description of the function by someone who already understands it. What I think is needed is an explanation of how to use it for someone who doesn't understand it.

What would be really good is a step by step description of the switch function you use in <OnGameEnd>. Although switch is a fairly easy to comprehend function the practice of it when it starts to include or, eq, if, etc tends to get a bit confusing.

I don't think it really is possible to be too detailed here. Using my favourite bit of code from Corp Trading Post in CorporateHierarchy.xml as an example (Thanks, George).

Code: Select all

<Action name="Place Order" default="1" key="P">
		(block (transport)
			; Create a transport at the nearest gate and put the item on it
			(setq transport (sysCreateShip &scEI100; (objGetNearestStargate gSource) &svCorporate;))
			(objAddItem transport gItem)

			; Order the transport to dock with the station and then gate out
			(shpOrderDock transport gSource)
			(shpOrderWait transport (random 5 10))
			(shpOrderGate transport)

			; Register the transport so we know if it got destroyed
			(objRegisterForEvents gSource transport)

			; Remember the item and the transport
			(objSetData gSource "Order" gItem)
			(objSetObjRefData gSource "Transport" transport)

			; Set the mission status
			(objSetData gSource "MissionStatus" "intransit")

			; Charge the player
			(plyCharge gPlayer gCost)
			(plyRecordBuyItem gPlayer gItem gCost)
			(objIncData gSource "OrderCount" 1)

			(scrShowPane gScreen "ThankYou")
			)
</Action>
I can actually understand half of this (although I can't write it yet) and would suggest that for a tutorial mod even more comments could be added.
Something like:

;When you press "P" this block of code creates a ship at the nearest stargate, puts the item(s) on it, pilots it to the Trading Post, docks, transfers the item(s) to the Trading Post, waits for a random length of time, pilots the ship back to the stargate and gates it out of the system. It also lets the computer know what to do if the ship gets destroyed, lets the computer know that the item(s) are on the way but not yet at the Trading Post, takes the money from the player and says "Thanks".
;setq means we are going to create or define something. In this case we will be creating a ship at a certain point and putting things inside it
;transport is the name given to this ship, it could have been called freighterthatdeliversitems or shipthatdropsoffitems but transport is shorter.
;sysCreateShip, as it says, creates a ship. In this case an EI100 freighter but any ship can be used. Just insert the desired ship class. Or possibly a random ship can be generated. Other will know how.
;objGetNearestStargate gSource is part of the sysCreateShip function. It tells the computer to create the ship at the nearest stargate (GetNearestStargate) to the gSource (in this case gSource is the Trading Post where the action is happening) Alternatively a ship can maybe be created at a set of coordinates or at a certain distance.
;SVCorporate is the sovereign. I don't know if this needs to be here or why.

And more info like this for every section of code.
It may seem too simple for modders with lots of experience, and it is very time consuming, but I feel this is the level of explanation that is needed to make it easier for people to mod.

It's certainly different from this:

Code: Select all

<Action name="Place Order" default="1" key="P">
		(block (transport)
			(setq transport (sysCreateShip &scEI100; (objGetNearestStargate gSource) &svCorporate;))
			(objAddItem transport gItem)
			(shpOrderDock transport gSource)
			(shpOrderWait transport (random 5 10))
			(shpOrderGate transport)
			(objRegisterForEvents gSource transport)
			(objSetData gSource "Order" gItem)
			(objSetObjRefData gSource "Transport" transport)
			(objSetData gSource "MissionStatus" "intransit")
			(plyCharge gPlayer gCost)
			(plyRecordBuyItem gPlayer gItem gCost)
			(objIncData gSource "OrderCount" 1)
			(scrShowPane gScreen "ThankYou")
		)
</Action>
which would have me bashing my head on the keyboard quite a lot.

The Trading Post code is only a very rough example and I've probably got a lot of it wrong. What I'm trying to convey is that you can't write code until you understand it, and you can't understand it until it has been explained with actual code examples. Preferably a lot of different examples. Repetition and redundancy are good things here.
That's my thoughts. Thanks for the mod. I learn something new every time I look at it.

Edited: thanks. Much nicer.
Last edited by relanat on Thu Nov 19, 2015 12:07 am, edited 1 time in total.
Stupid code. Do what I want, not what I typed in!
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm

Good stuff. I'll try and make things like that clearer across all .xml files in the next release.

A head up:

Code: Select all

[code]
[/code]

Is excellent for posting code.
RPC
Fleet Admiral
Fleet Admiral
Posts: 2876
Joined: Thu Feb 03, 2011 5:21 am
Location: Hmm... I'm confused. Anybody have a starmap to the Core?

Nice, gonna check this out and see what changed in the last few years :D
Tutorial List on the Wiki and Installing Mods
Get on Discord for mod help and general chat
Image
Image
Der Tod ist der zeitlose Frieden und das leben ist der Krieg
Wir müssen wissen — wir werden wissen!
I don't want any sort of copyright on my Transcendence mods. Feel free to take/modify whatever you want.
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm

RPC wrote:Nice, gonna check this out and see what changed in the last few years :D
Hope you like it. If you see anything that could use improvement, feel free to point it out in this thread.
relanat
Militia Captain
Militia Captain
Posts: 941
Joined: Tue Nov 05, 2013 9:56 am

Found a small bug.

Starting Trans and loading a previous Blue Light game gives:
Unable to load game
Unable to find type: 3801 (missing mod?)

Clicking OK and trying again makes it work. It only happens the first time you try to load a game. If you have already played a game and then quit then old games will load.

Thanks again.
Stupid code. Do what I want, not what I typed in!
JohnBWatson
Fleet Officer
Fleet Officer
Posts: 1452
Joined: Tue Aug 19, 2014 10:17 pm

relanat wrote:Found a small bug.

Starting Trans and loading a previous Blue Light game gives:
Unable to load game
Unable to find type: 3801 (missing mod?)

Clicking OK and trying again makes it work. It only happens the first time you try to load a game. If you have already played a game and then quit then old games will load.

Thanks again.
That'll be hard to test, but I'll see what I can do.
Post Reply