aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorywang <yw05@forksworld.de>2021-08-05 10:37:08 +0200
committerY. Wang <yw05@forksworld.de>2022-03-12 18:23:31 +0100
commit2c6385dbd4f439d1f4c669aa912840de17e123cd (patch)
treec5b7df29af1c4af0e82461a90aa1e4625db1ac2a
parent00e6b74cbcce03dc38b4dd7646de2533d35721f3 (diff)
downloadadvtrains-2c6385dbd4f439d1f4c669aa912840de17e123cd.tar.gz
advtrains-2c6385dbd4f439d1f4c669aa912840de17e123cd.tar.bz2
advtrains-2c6385dbd4f439d1f4c669aa912840de17e123cd.zip
Remove workaround in seven-segment display code; add documentation
-rw-r--r--advtrains/api_doc.txt42
-rw-r--r--advtrains/trainhud.lua34
2 files changed, 59 insertions, 17 deletions
diff --git a/advtrains/api_doc.txt b/advtrains/api_doc.txt
index 864e292..4ad554a 100644
--- a/advtrains/api_doc.txt
+++ b/advtrains/api_doc.txt
@@ -158,6 +158,48 @@ In case there are multiple possibilities, will show a form.
If you can't enter or leave a train because the doors are closed, holding the Sneak key while right-clicking bypasses the "doors have to be open" enforcement.
+# Train HUD
+The text_hud and graphical_hud fields of the wagons allow you to specify the look of your driver HUDs.
+* The text_hud function should return a string that will be shown to the driver. This should usually include the inside display as well
+* The graphical_hud function should return a texture string and the height of the texture. This is used to allow proper positioning of the text HUD.
+
+There are currently a few pre-defined elements that can help create the graphical HUD. These functions are in the advtrains.hud table:
+* texture_escape(str): a trivial function that escapes the textures
+* digit(digit, x, y, w, h, pc, nc): displays a single digit
+ * digit: the digit to display
+ * x, y: the upper-left corner of the digit display
+ * w, h: the width and height of a horizontal segment
+ * pc: the color to show when a given segment is lit
+ * nc: the color to show when a given segment is not lit
+* number(num, length, x, y, w, h, margin, pc, nc): displays a non-negative integer, possibly using multiple 7-segment displays:
+ * num: the number to display
+ * length: the numbers of digits to display (if nil: the number of digits in the number).
+ * x, y: the upper-left corner of the digit display
+ * w, h, pc, nc: (see above)
+ * margin: the margin between each digit
+ * The behavior of num>=10^length is undefined.
+* leverof(train): returns the lever of the train. This should be preferred over train.lever
+* lever(lever, x, y, w1, w2, h): draws a lever
+ * lever: the lever of the train
+ * x, y: the upper-left corner of the lever
+ * w1: the width of the merkers beside the lever
+ * w2: the width of the handle
+ * h: the height of the lever
+ * In the context of drawing (i.e. the description of the x, y, w1, w2, and h arguments), "the lever" refers to the area that the actual lever is drawn in, not the lever itself.
+* door(o, x, y, w, h, m): draws a simple door indicator
+ * o: the state of the door
+ * x, y, w, h: the upper-left corner and the size of the indicator
+ * m: the margin between the elements of the indicator
+ * The indicator includes an indicator for each door and a simple shape showing a vehicle
+ * Due to the internals of this function, it is recommended that (w-2*m) is a multiple of 4
+* speed_horizontal(train, x, y, w, h, m): draws a horizontal bar showing the speed
+ * train: the train table
+ * x, y, w, h: the upper-left cornder and the size of the indicator
+ * m: the margin between the elements of the indicator
+ * h must be greater than 10
+ * Due to the internals of this function, it is recommended that (w-19*m) is a multiple of 20
+* In the above functions, the behavior of negative coordinates and magnitudes (e.g. width, height, margin) and invalid data is undefined.
+
### Tracks
Most modders will be satisfied with the built-in tracks. If cog railways, maglev trains and mine trains are added, it is necessary to understand the definition of tracks. Although the tracks API is there, explaining it would require more effort than me creating the wanted definitions myself. Contact me if you need to register your own rails using my registration functions.
diff --git a/advtrains/trainhud.lua b/advtrains/trainhud.lua
index 8d719ed..3e5e6fd 100644
--- a/advtrains/trainhud.lua
+++ b/advtrains/trainhud.lua
@@ -199,7 +199,7 @@ function advtrains.hud.dtext(train, flip)
return table.concat(st, "\n")
end
-function advtrains.hud.sevenseg(digit, x, y, w, h, m, d)
+function advtrains.hud.sevenseg(digit, x, y, w, h, pc, nc)
local st = {}
local sformat = string.format
local f = "%d,%d=(advtrains_hud_bg.png^[resize\\:%dx%d%s)"
@@ -221,24 +221,25 @@ function advtrains.hud.sevenseg(digit, x, y, w, h, m, d)
[6] = {true, true, false, true, true, true, true},
[7] = {true, false, true, false, false, true, false},
[8] = {true, true, true, true, true, true, true},
- [9] = {true, true, true, true, false, true, true}}
+ [9] = {true, true, true, true, false, true, true}
+ }
local ent = trans[digit or 10]
if not ent then return end
for i = 1, 7, 1 do
if ent[i] then
local s = segs[i]
- st[#st+1] = sformat(f, x+s[1], y+s[2], s[3], s[4], m and "^"..m or "")
- elseif d then
+ st[#st+1] = sformat(f, x+s[1], y+s[2], s[3], s[4], pc and "^[colorize\\:"..pc or "")
+ elseif nc then
local s = segs[i]
- st[#st+1] = sformat(f, x+s[1], y+s[2], s[3], s[4], "^"..d)
+ st[#st+1] = sformat(f, x+s[1], y+s[2], s[3], s[4], "^[colorize\\:"..nc)
end
end
return table.concat(st,":")
end
-function advtrains.hud.number(number, padding, x, y, w, h, margin, modifier, dark)
+function advtrains.hud.number(number, padding, x, y, w, h, margin, pcolor, ncolor)
local st = {}
- local number = math.abs(math.floor(number))
+ local number = math.abs(math.floor(number or 0))
if not padding then
if number == 0 then
padding = 0
@@ -249,7 +250,7 @@ function advtrains.hud.number(number, padding, x, y, w, h, margin, modifier, dar
padding = padding - 1
end
for i = padding, 0, -1 do
- st[#st+1] = advtrains.hud.sevenseg(math.floor(number/10^i)%10, x+(padding-i)*(w+2*h+margin), y, w, h, modifier, dark)
+ st[#st+1] = advtrains.hud.sevenseg(math.floor(number/10^i)%10, x+(padding-i)*(w+2*h+margin), y, w, h, pcolor, ncolor)
end
return table.concat(st,":")
end
@@ -321,7 +322,6 @@ end
function advtrains.hud.dgraphical(train, flip)
if not train then return "" end
local sformat = string.format -- this appears to be faster than (...):format
- local sevenseg = advtrains.hud.sevenseg
local max = train.max_speed or 10
local vel = advtrains.abs_ceil(train.velocity)
@@ -354,38 +354,38 @@ function advtrains.hud.dgraphical(train, flip)
local c = not spd and "lime" or (type(spd) == "number" and (spd == 0) and "red" or "orange") or nil
if c then
if spd then
- ht[#ht+1] = advtrains.hud.number(spd, 2, 10, 45, 5, 2, 2, "[colorize\\:"..c, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(spd, 2, 10, 45, 5, 2, 2, c, "darkslategray")
ht[#ht+1] = sformat("10,67=(advtrains_hud_ms.png^[multiply\\:%s)", c)
else
- ht[#ht+1] = advtrains.hud.number(88, 2, 10, 45, 5, 2, 2, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(88, 2, 10, 45, 5, 2, 2, "darkslategray")
ht[#ht+1] = "10,67=(advtrains_hud_ms.png^[multiply\\:darkslategray)"
end
local floor = math.floor
local dist = floor(((oc[i].index or train.index)-train.index))
dist = math.max(0, math.min(999, dist))
- ht[#ht+1] = advtrains.hud.number(dist, 3, 35, 45, 9, 4, 2, "[colorize\\:"..c, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(dist, 3, 35, 45, 9, 4, 2, c, "darkslategray")
noupcoming = false
break
end
end
end
if noupcoming then
- ht[#ht+1] = advtrains.hud.number(88, 2, 10, 45, 5, 2, 2, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(88, 2, 10, 45, 5, 2, 2, "darkslategray")
ht[#ht+1] = "10,67=(advtrains_hud_ms.png^[multiply\\:darkslategray)"
- ht[#ht+1] = advtrains.hud.number(888, 3, 35, 45, 9, 4, 2, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(888, 3, 35, 45, 9, 4, 2, "darkslategray")
end
ht[#ht+1] = sformat("100,45=(advtrains_hud_atc.png^[multiply\\:%s)", (train.tarvelocity or train.atc_command) and "cyan" or "darkslategray")
if tar and tar >= 0 then
local tc = math.min(max, tar)
- ht[#ht+1] = advtrains.hud.number(tar, 2, 135, 45, 5, 2, 2, "[colorize\\:cyan", "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(tar, 2, 135, 45, 5, 2, 2, "cyan", "darkslategray")
ht[#ht+1] = "135,67=(advtrains_hud_ms.png^[multiply\\:cyan)"
else
- ht[#ht+1] = advtrains.hud.number(88, 2, 135, 45, 5, 2, 2, "[colorize\\:darkslategray")
+ ht[#ht+1] = advtrains.hud.number(88, 2, 135, 45, 5, 2, 2, "darkslategray")
ht[#ht+1] = "135,67=(advtrains_hud_ms.png^[multiply\\:darkslategray)"
end
ht[#ht+1] = advtrains.hud.door(train.door_open, 167, 45, 60, 30, 2)
-- speed indications
- ht[#ht+1] = advtrains.hud.number(vel, 2, 320, 10, 35, 10, 10, "[colorize\\:red\\:255")
+ ht[#ht+1] = advtrains.hud.number(vel, 2, 320, 10, 35, 10, 10, "red")
ht[#ht+1] = advtrains.hud.speed_horizontal(train, 10, 80, 217, 30, 3)
return table.concat(ht,":"), 120