MGFX

简体中文

English

简体中文

English

Appearance

文本 API ​

字体别名、文本样式、测量、预热、原生文本路径和 shader text effects。

适用边界 ​

  • 普通 label、scoreboard、表格、日志和聊天优先用原生 GMod text。
  • 只有需要渐变字面、描边、glow、shadow、surface polish 等 shader 特效时才进入 MGFX text composer。
  • 稳定的特效文本可以用 PrewarmText 提前烘焙。

本页 API ​

路径选择 ​

需求推荐路径原因
玩家名、聊天、日志、表格、快速变化数字Text 或原生 GMod text最少开销，不需要整段 glyph composer。
单行 HUD 标签，有轻微阴影Text 或 TextEx 加轻量 shadow只要 x = 0, y = 1..2, blur = 1..3 即可。
标题、击杀提示、奖励数字TextEx需要 stroke/glow/gradient 时进入 composer。
固定宽度描述、技能说明、列表列名TextBoxEx + MeasureTextBox先测量再绘制，避免手工算 baseline 和省略号。
稳定重复文本PrewarmText适合标题、列名、固定标签；不适合每帧都变的唯一字符串。

普通文字不要为了“统一”强行用 TextEx。只有 style 里出现 fill 渐变、stroke、glow、shadow、surface、tracking、lineHeight 等高级排版/特效时，才值得走 composer。

常用文本配方 ​

原生普通标签 ​

lua
MGFX.Text(playerName, "DermaDefault", x, y, Color(230, 238, 245), TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER)

这是 scoreboard、玩家名和行内数字的默认选择。

清晰 HUD 数字 ​

lua
MGFX.TextEx("128,450", "ScoreNum", x, y, Color(236, 248, 255), TEXT_ALIGN_RIGHT, TEXT_ALIGN_CENTER, {
    stroke = {width = 0.45, softness = 0.66, color = Color(0, 0, 0, 120)},
    shadow = {x = 0, y = 2, blur = 4, color = Color(0, 0, 0, 120)},
})

普通字号先用 stroke.width = 0.3..0.8。标题可以到 1.0..1.6，再高会吃掉字面细节。

Glow 标题 ​

lua
MGFX.TextEx("ROUND 4", "ScoreTitle", x, y, nil, TEXT_ALIGN_CENTER, TEXT_ALIGN_CENTER, {
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(255, 255, 255), Color(130, 210, 255)),
    stroke = {width = 0.9, softness = 0.58, color = Color(2, 9, 12, 185)},
    glow = {size = 6, color = Color(66, 188, 255, 72), opacity = 0.65, softness = 0.58},
    shadow = {x = 0, y = 2, blur = 5, color = Color(0, 0, 0, 140)},
    surface = {strength = 0.12},
})

glow.size = 4..10 适合 HUD 标题，opacity = 0.4..0.8 常用。surface.strength = 0.08..0.18 是很轻的字面 polish，不要当描边用。

多行说明 / 省略号 ​

lua
local tw, th = MGFX.MeasureTextBox(description, "ScoreSmall", 220, {
    lineHeight = 18,
    overflow = "ellipsis",
})

MGFX.TextBoxEx(description, "ScoreSmall", x, y, 220, th, {
    fill = Color(220, 230, 245),
    alignX = TEXT_ALIGN_LEFT,
    alignY = TEXT_ALIGN_TOP,
    lineHeight = 18,
    overflow = "ellipsis",
    shadow = {x = 0, y = 1, blur = 2, color = Color(0, 0, 0, 95)},
})

overflow = "ellipsis" 返回单行省略文本。省略 overflow 时按宽度换行。

参数速查 ​

字段推荐范围说明
font.size小字 13..16，正文 16..20，标题 24..36注册字体时写实际 UI 字号，MGFX 内部会按需要 oversample。
font.weight正文 400..550，强调 600..750，数字标题 700..900也接受 1..10 快捷值，但公开文档推荐写真实 weight。
lineHeightfont.size + 2..6多行和文本框必须显式控制，避免不同字体 baseline 漂移。
tracking / letterSpacing0..1.5英文小 caps 可用；中文/CJK 大多保持 0。
shadow.x/ylabel y = 1..2，标题 y = 2..5正 x 向右，正 y 向下。
shadow.blurlabel 1..3，标题 4..8文本阴影的软边，和偏移分开。
stroke.width普通 0.3..0.8，标题 0.9..1.6数值过大会吞掉笔画；先调 color alpha，再调 width。
stroke.softness0..1，常用 0.55..0.75越大越柔，硬像素描边用 0.35..0.55。
glow.size小标签 3..5，标题 5..10glow 太大时优先降低 color alpha 或 opacity。
glow.opacity0.4..0.8 常用实现接受数字强度；常规 UI 不建议超过 1。
weightAdjust-0.4..0.6 常用bold 和 thin 是快捷值；细调时直接写数字。

函数参考 ​

RegisterTextFont ​

lua
MGFX.RegisterTextFont(name, spec)

注册 MGFX 文本字体别名。

参数 ​

参数说明
nameMGFX 文本调用使用的公共字体别名。
spec.face原生字体 face 名称。
spec.size, weight, lineHeight字体度量和变体提示。

用法说明 ​

  • 绘制需要 shader 文本特效的文本前先注册字体。
  • TextBox 需要稳定垂直节奏时请包含 lineHeight。

返回值 ​

根据渲染器注册是否成功返回 true/false。

字体 spec 字段 ​

字段 / 可接受值默认值作用
face / font
系统字体名称。		nil创建 MGFX 原生合成字体别名。
sourceFont / nativeFont
已有 GMod 字体名称。		fontName省略 face 时使用已有 surface 字体。
size
数字。		16MGFX 过采样前的字体大小。
weight
100..1200，或 1..10 快捷值。		500 / 400 for Noto Sans SC原生字体字重。
italic
布尔值。		false创建斜体原生字体变体。
lineHeight / lineheight
数字。		measured Hg height此别名的默认行高。
tracking / letterSpacing
数字。		0默认字符间距。
syntheticWeight / allowSyntheticWeight
布尔值。		false允许样式侧合成字重调整。

示例 ​

lua
MGFX.RegisterTextFont("ScoreTitle", {
    face = "Noto Sans SC",
    size = 28,
    weight = 700,
    lineHeight = 32,
})

DefineTextStyle ​

lua
MGFX.DefineTextStyle(name, style)

存储可复用文本样式记录。

参数 ​

参数说明
name样式名称。
style文本样式表：fill、stroke、glow、shadow、tracking、lineHeight 等。

用法说明 ​

  • 样式是显式值；MGFX 没有公共样式栈。
  • 用于重复的 scoreboard 标签和标题。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

示例 ​

lua
MGFX.DefineTextStyle("ScoreGlow", {
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(255, 255, 255), Color(130, 210, 255)),
    glow = {size = 5, color = Color(80, 170, 255, 110)},
})

GetTextStyle ​

lua
MGFX.GetTextStyle(name)

获取之前定义的文本样式。

参数 ​

参数说明
name传给 DefineTextStyle 的样式名。

用法说明 ​

  • 把返回的样式传给 TextEx 或 TextBoxEx。
  • 样式不存在或文本渲染器不可用时返回 nil。

返回值 ​

文本样式表或 nil。

示例 ​

lua
local titleStyle = MGFX.GetTextStyle("ScoreGlow")
MGFX.TextEx("ROUND 4", "ScoreTitle", x, y, nil, TEXT_ALIGN_LEFT, TEXT_ALIGN_TOP, titleStyle)

ResolveTextStyle ​

lua
MGFX.ResolveTextStyle(style)

规范化文本样式表以便复用。

参数 ​

参数说明
style原始文本样式表，或已经解析过的样式。

用法说明 ​

  • 当你构建一次样式并传给多个文本调用时很有用。
  • 已解析样式会原样返回。

返回值 ​

解析后的样式表。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

示例 ​

lua
local rowStyle = MGFX.ResolveTextStyle({
    fill = Color(230, 240, 255),
    shadow = {x = 0, y = 1, blur = 2, color = Color(0, 0, 0, 120)},
})

MeasureText ​

lua
MGFX.MeasureText(text, font)

测量单段文本。

参数 ​

参数说明
text文本值，按 tostring 语义转换。
font字体别名或原生字体名。

用法说明 ​

  • 用于定位标签或预留稳定单元格宽度。
  • 换行或省略文本框请使用 MeasureTextBox。

返回值 ​

width, height。

示例 ​

lua
local tw, th = MGFX.MeasureText(playerName, "ScoreRow")
MGFX.Text(playerName, "ScoreRow", x + w - tw, y, color_white)

MeasureTextBox ​

lua
MGFX.MeasureTextBox(text, font, w, style)

为固定宽度文本框测量换行或省略后的文本。

参数 ​

参数说明
w可用文本框宽度。
style文本框样式，包括换行和行高选项。

用法说明 ​

  • 在密集行中绘制变长标签前使用。
  • 回退路径返回单行测量。

返回值 ​

width, height, lines。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

文本框字段 ​

字段 / 可接受值默认值作用
overflow
"ellipsis" 或省略。		wrap省略表示按字符换行。ellipsis 返回一行缩略文本。
alignX / align
left、center、right，或 TEXT_ALIGN_*。		left文本框内每行的水平位置。
alignY / valign
top、center/middle、bottom，或 TEXT_ALIGN_*。		top换行文本块的垂直位置。

示例 ​

lua
local tw, th = MGFX.MeasureTextBox(description, "ScoreSmall", 220, {wrap = true, lineHeight = 18})

PrewarmText ​

lua
MGFX.PrewarmText(text, font, style)

在首次绘制前把稳定文本烘焙进合成图集。

参数 ​

参数说明
text, font要预热的文本段。
style可选文本样式。

用法说明 ​

  • 最适合稳定标题、标签、表格列名和重复 scoreboard 文本。
  • 不要预热高度唯一且大量变化的值。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

示例 ​

lua
MGFX.PrewarmText("SCORE", "ScoreTitle", MGFX.GetTextStyle("ScoreGlow"))

Text ​

lua
MGFX.Text(text, font, x, y, color, ax, ay)

简单文本绘制 helper。

参数 ​

参数说明
color字面颜色。
ax, ayGMod 文本对齐常量。

用法说明 ​

  • 在 MGFX 帧内，文本会排队并在 EndPanel/EndScreen 刷新。
  • 需要渐变字面、描边、发光、阴影、字距或行高控制时使用 TextEx。

示例 ​

lua
MGFX.Text("READY", "DermaLarge", x, y, color_white, TEXT_ALIGN_CENTER, TEXT_ALIGN_CENTER)

TextEx ​

lua
MGFX.TextEx(text, font, x, y, color, ax, ay, style)

带合成特效的高级文本绘制。

参数 ​

参数说明
style.fillColor 或 MGFX 渐变字面绘制。
style.stroke描边表，含 width、color、softness。
style.glow / shadow文本发光和阴影特效。
style.tracking / lineHeight排版间距控制。

用法说明 ​

  • 仍接受 color，但 style.fill 是高级字面绘制槽位。
  • 普通文本保持 GMod 原生绘制。shader 特效文本会按整段烘焙，并从图集里合成绘制。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

示例 ​

lua
MGFX.TextEx(value, "ScoreStat", x, y, nil, TEXT_ALIGN_RIGHT, TEXT_ALIGN_TOP, {
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(255, 255, 255), Color(130, 210, 255)),
    glow = {size = 4, color = Color(80, 170, 255, 110)},
})

TextBox ​

lua
MGFX.TextBox(text, font, x, y, w, h, color, alignX, alignY)

简单文本框绘制 helper。

参数 ​

参数说明
w, h文本框边界。
color文本颜色。
alignX, alignY水平和垂直对齐常量。

用法说明 ​

  • 用于固定矩形中的普通对齐文本。
  • 需要换行、省略、行高和特效时使用 TextBoxEx。

示例 ​

lua
MGFX.TextBox(playerName, "ScoreRow", x, y, 180, 24, color_white, TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER)

TextBoxEx ​

lua
MGFX.TextBoxEx(text, font, x, y, w, h, style)

支持换行、对齐和合成特效的高级文本框。

参数 ​

参数说明
style.fill / color文本字面绘制。
style.alignX / alignY文本框对齐。
style.lineHeight行高覆盖。
style.wrap / ellipsis受支持时的文本布局行为。
style.stroke, glow, shadow合成特效。

用法说明 ​

  • TextBoxEx 会在活动 MGFX 帧内排队文本框命令。
  • 布局需要先得到精确测量时使用 MeasureTextBox。

文本 style 字段 ​

字段 / 可接受值默认值作用
extends / base
样式名、样式表，或样式数组。		nil继承已定义文本样式。
fill / color
Color 或 MGFX 渐变记录。		call color or white文字面填充。
alignX / align / alignY / valign
TEXT_ALIGN_* 常量，或 left/center/right/top/bottom 字符串。		call args / top-left文本锚点或文本框对齐。
lineHeight
数字。		font alias or measured height多行文本和文本框的行距。
tracking / letterSpacing
数字。		font alias tracking字符间额外间距。
shadow
true、数字，或 {x/offsetX, y/offsetY, blur/radius, color/tint, strength}。		nil合成文本投影。
stroke / outline
true、数字，或 {width/size, color/tint, samples, softness}。		nil文本描边。
glow
true、数字，或 {size, color/tint, opacity, softness}。		nil文本发光 pass。
surface
true、数字，或 {strength}。		nil轻量字面 polish，常用 strength 0.08..0.18。
bold / thin / weightAdjust
布尔快捷值，或 -2 到 2 的数字。		0合成边缘字重调整。
italic
布尔值。		false可能时请求斜体原生字体变体。

文本框字段 ​

字段 / 可接受值默认值作用
overflow
"ellipsis" 或省略。		wrap省略表示按字符换行。ellipsis 返回一行缩略文本。
alignX / align
left、center、right，或 TEXT_ALIGN_*。		left文本框内每行的水平位置。
alignY / valign
top、center/middle、bottom，或 TEXT_ALIGN_*。		top换行文本块的垂直位置。

示例 ​

lua
MGFX.TextBoxEx(description, "ScoreSmall", x, y, w, 42, {
    fill = Color(220, 230, 245),
    alignX = TEXT_ALIGN_LEFT,
    alignY = TEXT_ALIGN_TOP,
    lineHeight = 18,
    shadow = {x = 0, y = 1, blur = 2, color = Color(0, 0, 0, 140)},
})

返回详细 API 入口