Autor zarchiwizował to repozytorium, więc nie jest już rozwijane.
README.md
samp-unicode
简体中文 | Português (BR) | Русский | 日本語 | English
A client-side mod (an .asi) for SA-MP that draws the client's text with a real Unicode
font, so server text in any encoding — GBK, Big5, Shift-JIS, EUC-KR, Cyrillic, UTF-8 — shows
up readable instead of mojibake.
"All of it" is meant literally: TextDraw, GameText and the native Menu and everything
the client itself paints with ID3DXFont — the chat box and its lines, every dialog style,
the TAB scoreboard, 3D text labels, nametags, chat bubbles, the death window, object material
text and the license plate (Client text). The client's own decoding (the
system ANSI code page) never sees a string: the bytes are decoded once by this mod and drawn
from a font that has the glyphs.
The game keeps its own layout, timing, colour and visibility; only the glyphs change. Latin
text drawn with the four original TextDrawFont faces keeps those faces, CJK falls back to a
Unicode display font, and each surface keeps the shadow the client itself asked for. The one
thing the mod cannot change is what is typed: the chat line and the dialog input field are
read back by the client as single bytes in the system ANSI code page, so a character that
page cannot hold is lost on submit (Limitations).
The scoreboard still decides two things for the overlay, both matched to the client: while its panel is open the TextDraw layer is dropped (the client skips its whole textdraw pass there) and the GameText layer is drawn behind the translucent panel (Scoreboard).
TextDraw on the right, the native menu on the left, GameText along the bottom - the same five languages, drawn by the mod.
Install
- Copy
samp-unicode.asi(and, if you want the blackletter face,font0.ttf) intoGTA San Andreas\modloader\samp-unicode\— or anywhere else the ASI loader picks up. - Start the game once.
samp-unicode.iniandsamp-unicode.logappear next to the.asi.
Compatibility
This mod replaces the text the game draws, so it cannot share that text with another mod that does the same. Run one text-replacing mod at a time.
| Conflicts | Why |
|---|---|
| Other Chinese/Cyrillic font mods for SA-MP | Both hook CTextDraw::Draw / CGame::DisplayGameText / CFont::PrintString and both blank the source text. At best the strings are drawn twice (once per font), at worst each mod blanks what the other wanted to draw, so text vanishes or turns into spaces. |
"GameText fix" / fixes.inc client helpers that also patch CGame::DisplayGameText | Same function, both patch the same bytes. Whichever installs second usually wins and the other's trampoline is left pointing at patched code. |
| Any overlay that replaces the D3D9 device with a proxy object | The mod refuses to hook a device whose vtable lives in heap memory (it would fight the proxy). It logs proxy object, leaving it alone and becomes a no-op: the game's own bitmap text shows, nothing breaks. |
Known to work alongside (tested on a real install): modloader itself, SilentPatch,
III.VC.SA.LimitAdjuster, WidescreenFix, WindowedMode, FramerateVigilante,
PreciseFramerateLimiter, SAMPGraphicRestore/ENB, and CLEO scripts that do not draw
text themselves.
If the log says endpoint ... already hooked or the screen shows every string
twice, another mod is in the same place: disable it and restart.
Configuration
A fresh samp-unicode.ini is written next to the .asi on first start; every key
below is in it and every key is optional (a missing key keeps its default).
[font]
file =
family =
collection = 0
face =
font0 =
font1 =
font2 =
font3 =
size_divisor = 50
baseline_offset = 0
glyph_gamma = 0.80
shadow = on
letter_width = on
client_glyphs = on
shadow_offset = 1, 1
[textdraw]
fonts = 0, 1, 2, 3
brace_colors = off
scoreboard_layer = under
[menu]
enabled = on
font = 2
title_font = 0
title_scale = 1.00
title_dy = 0
title_width = 0.80
hscale = 1.00
align = 0
glyph = 1.0
outline = 1
shadow = 3
title_outline = 2
title_shadow = 0
shadow_color = 000000
shadow_alpha = 255
color = 0
[gametext]
enabled = on
fade_out = on
ignore_styles = none
scale = 0.82
[encoding]
charset = auto
utf8_first = on
redraw_ascii = off
detect = on
[debug]
log = on
verbose = off
[overlay]
hook_point = present
| Key | Default | Meaning |
|---|---|---|
font.file / font.family | empty | Display font: the face that carries the station charset. family takes a CSS-like list (Noto Sans SC, Microsoft YaHei, sans-serif); the first entry that exists and covers the charset wins, and sans-serif / system-ui / serif are understood. Entries may be quoted like in CSS ("Source Han Sans SC"), which also allows a comma inside a name. Empty = samp-unicode.ttf next to the .asi, then the built-in order (YaHei, Noto Sans SC, Source Han Sans, PingFang, HarmonyOS Sans, MiSans, SimHei, SimSun, KaiTi, …). |
font.collection | 0 | Index inside a .ttc. Faces without a name are skipped automatically. |
font.face | empty | Family name for a .ttc whose name table is unusable (simsun.ttc); when empty the name is read from the file. |
font.font0 … font.font3 | empty | Face for TextDrawFont 0-3: an installed family name, a font file, or empty = fontN.ttf / samp-unicode-fontN.ttf from the mod folder, else the closest installed face. |
font.size_divisor | 50 | Pixel height = letter_height * screen_height / size_divisor. 50 makes one line as tall as the client's own 20H cell (measured against the stock renderer: 48 is the exact cell and 50 compensates for our slightly taller ink); raise it if the text looks too large on a page, lower it if a page looks too small. |
font.baseline_offset | 0 | Vertical nudge in pixels. |
font.glyph_gamma | 0.80 | Maps GDI's coverage before it becomes the glyph's alpha. Below 1 the middle coverage rises, so a stroke keeps its weight while its edge tightens — GDI spreads an edge over more pixels than the client's own rasteriser, which reads as soft text next to it. 1.00 is GDI's coverage untouched. Applies where the glyph texture is built, so every surface shares it. |
font.shadow / font.shadow_offset | on / 1, 1 | Optional drop shadow, offset in pixels. |
font.letter_width | on | Stretch each run to the width the game reserved from letterWidth (keeps the server's aspect ratio). |
font.client_glyphs | on | Draw the symbol the client's own face draws for a few punctuation characters instead of the character itself: face 2 shows a star for ] and nothing for [. off keeps plain brackets. |
overlay.hook_point | present | present draws at Present, i.e. above every other overlay (default). endscene draws at EndScene, which runs earlier in the frame, so what other mods draw at Present - omp-client's Dear ImGui settings window (F9), RTSS, other ImGui mods - is drawn above ours. |
textdraw.fonts | 0, 1, 2, 3 | Font ids to re-render; 4/5 are sprite and model preview. all = every id. |
textdraw.brace_colors | off | Also read {RRGGBB} / {RRGGBBAA} braces as colour changes. The client itself does not, so this only makes sense for a server that prints them on purpose (chat syntax). |
textdraw.scoreboard_layer | under | under draws the GameText and native-menu layers before the scoreboard panel, so the panel covers them (the text shows through its translucency, the menu sits below it) and — because the panel is translucent — the text shows through it like the client's own. hide skips the layer while the panel is open, which is the fallback when the panel's draw cannot be hooked. |
menu.enabled | on | Take over Menu text (title, column headers, rows). |
menu.font | 2 | Face for menu rows: 0-3, see [font]. |
menu.title_font | 0 | Face for the menu title. The client draws the title with face 0 (the same one TextDrawFont 0 uses), so that is the default. |
menu.title_scale / menu.title_dy | 1.00 / 0 | Size multiplier and pixel offset for the title only. The client draws the title with the tall face and lets it straddle the panel's top edge. |
menu.title_width | 0.80 | Glyph width of the title relative to a row glyph. The client's title face is narrow but tracked wide; a substitute face cannot match both, so this is calibrated for the width the client gives the title (hello = 71 px at 40 px tall). Lower it for narrower letters, raise it for wider. |
menu.hscale | 1.00 | Horizontal squeeze for menu rows. GDI advances run slightly wider than the client's own metrics; 0.95-1.00 brings the line width closer without changing the height. |
menu.align | 0 | Pen alignment: 0 = text starts at x, 1 = centred, 2 = right. |
menu.glyph | 1.0 | Size multiplier for menu text (1.0 = the size the game itself uses). |
menu.outline / menu.shadow | 1 / 3 | Rows: outline and drop shadow, both in pixels at a 20-px reference size and scaled with the text. The shadow is drawn under the outline, so it only shows where it is wider. |
menu.title_outline / menu.title_shadow | 2 / 0 | The same two for the title, which is drawn much larger than the rows (2 becomes 4 px at 40 px tall). |
menu.shadow_color / menu.shadow_alpha | 000000 / 255 | Shadow colour (RRGGBB) and its alpha. 255 is opaque black like the game; lower it for a softer shadow. |
menu.color | 0 | RRGGBB to force one colour, 0 = use the colour the game set for that line. |
gametext.enabled | on | Take over GameText at all. off leaves every message to the client. |
gametext.ignore_styles | none | Styles kept on the game's own renderer (0-6); none / all. |
gametext.scale | 0.82 | Multiplier for the built-in per-style text height. 0.82 is measured against the client's own GameText: its cap height is 45 px where this renderer produced 55 at 1.0 on the same style and screen. |
gametext.fade_out | on | Fade the last ~400 ms. Off cuts the message at full brightness. |
encoding.charset | auto | auto, a name (gbk, big5, sjis, euc-kr, cp1251, utf-8, …) or a number. |
encoding.utf8_first | on | Try strict UTF-8 before the charset. |
encoding.detect | on | With auto, detect CJK/Cyrillic encodings. A byte pair that is valid in both UTF-8 and the legacy codepage is taken as legacy CJK. |
encoding.redraw_ascii | off | Draw pure-ASCII text with our renderer as well. Off keeps the client's own bitmap font for English, so an all-English line looks exactly like an unmodded client. |
debug.log / debug.verbose | on / off | Log file switch and per-texture detail. |
auto means the player's Windows ANSI code page, so 欢迎来到服务器 (GBK),
日本語のテスト (Shift-JIS) or Привет (CP1251) are decoded correctly on any
system once detect = on; Latin-1 is never reinterpreted.
The [paths] block that decides which surfaces are taken over — client_text = off | log | draw, the face and width of that text, how thick its shadow is and whether the
client's own shadow passes are dropped — is documented key by key in
CLIENT-TEXT.md, together with the hook points.
Detection is a guess, and a named encoding beats it. charset = auto is a
heuristic: a short string without spaces is genuinely ambiguous (D2 BB is both GBK
一 and a valid UTF-8 character), and no detector resolves every case. In practice a
server sends everything in one encoding, so name it - charset = 936 (or 950, 932,
949, 1251) - and the mod stops guessing. Every surface that shows text is decoded here,
so the ANSI code page only matters to what the client submits from its own edit boxes.
One global configuration, and short text is the weak spot. There are no
per-server profiles: samp-unicode.ini is read once at start and applies to whatever
server the player joins next. Detection is weakest exactly where the strings are
shortest - a menu column header or a two-character label carries too few bytes to be
certain - so a player who alternates between servers in different languages would have
to edit the INI each time. That is not a workflow this mod tries to support.
Build
msbuild samp-unicode.vcxproj /nologo /p:Configuration=Release /p:Platform=Win32
or build.bat from an x86 Native Tools Command Prompt. Output:
bin\Release\samp-unicode.asi. CI (Actions → build → Run workflow) builds
Release and uploads samp-unicode-release.zip with the .asi, the generated
.ini and the licences.
How it works
CTextDraw::Draw (text branch) → collect text/position/size/colour, hide the
game's glyphs, call the game function
CGame::DisplayGameText → collect text/style/duration, feed spaces
CMenu::Show + display-list → learn the menu title/rows and where they go
CFont::PrintString (menu text) → hide the line and draw it at the same pen
ID3DXFont::DrawTextA/W → the client's own text: chat, labels, dialogs,
scoreboard, nametags, death window. Drop its
shadow copies, remember the pairing
CFontWrapper vtable → the same lines one level lower (DXUT text,
buttons, rows, chat) - decoded and redrawn
CDXUTDialog::OnRender sites → queue that panel's text for after its fill
D3D9 Present (vtable) → one textured quad per text run
D3D9 BeginScene (vtable) → paste the background back on a frozen frame
The overlay draws at Present, so the surface it captures, restores and draws on is
the one that is shown. That matters for menus: the client stops repainting the area
while a menu or the pause menu is up, and the only way to remove text there is to put
the background back - see Known issues.
Text goes bytes → UTF-16 → GDI raster → D3D9 texture → quad, so the glyphs
come from the installed font instead of GTA's fixed bitmap font. TextDraws keep
the game's layout, timing and visibility; GameText is placed, timed and faded
from the style table below.
- colours: see Colours below
- long text: a run that does not fit one 4096x512 texture is truncated, not dropped
- line breaks:
~n~and real newlines - sprites: font ids
4/5use another renderer (CSprite2d) and are untouched
Menu
CMenu::Show only builds the panel; the title, headers and rows are drawn every
frame by CFont::PrintString, which is why a menu shows mojibake while the rest
of the screen is fine. The mod hooks that call, but only takes a line over when
all of these hold:
- a menu is on screen (
CMenu::Showran within the last few seconds, refreshed while its text keeps being drawn); - the string is not pure ASCII (English rows keep the game's own look);
- the line was drawn with the font state the menu itself uses — the scoreboard, 3D labels and chat use different sizes and pass straight through.
The title is the odd one out: the client draws it with the tall face and a
non-square scale, so it is 40 px tall and 71 px wide for hello where the rows'
face would give half that height. src/hooks.cpp matches the height through its
own base and the width through [menu] title_width, both measured against the
client on a real menu.
Scoreboard
The client draws its scoreboard after the HUD pass, so its own GameText ends up
under the panel. The overlay runs at Present, i.e. after everything, which
would paint GameText on top of the list instead. The panel's own draw is therefore
hooked: the GameText layer is drawn first and the panel over it, so with the
panel's translucency the text is visible through it exactly as the client's is,
and the message keeps its clock. When that hook cannot be installed (a build
without the expected prologue) the layer is skipped instead - the message is
queued, its clock runs, and it is gone or shorter when the panel closes, which is
what scoreboard_layer = hide asks for explicitly. TextDraws are a different story: the client skips its whole textdraw pass while the panel is open - the loop that calls the textdraw renderer is guarded by cmp [CScoreboard], 0; jne right in front of it - so the overlay drops the TextDraw layer too instead of painting it over the panel. The native menu is a third layer: the client keeps drawing it, so the overlay paints it below the panel as well, above the GameText, exactly where the client has it.
The panel's own "shown" flag decides that, not a key: in this client TAB is a toggle (press to open, press again or ESC to close), so a key check would be wrong in both directions. The flag is found from the structure around the panel's draw call, never from a fixed address (see Verified). If it cannot be located, the layer simply stays over the panel as before, which the log reports.
Client text
The client draws its own interface text with ID3DXFont, in single-byte strings: the chat,
the scoreboard, every dialog style, the 3D labels, the nametags, the chat bubbles, the death
window, the object material text and the license plate. Every one of them loses text the
ANSI code page cannot represent. [paths] client_text = draw takes those draws over and
paints them with this mod's font, so a server's Chinese chat, names, dialogs and signs
appear as typed.
The whole set works on every build the launcher offers (0.3.7-R1 through R5 and 0.3.DL), not just 0.3.DL:
| Surface | Reached through |
|---|---|
| 3D labels, nametags, chat bubbles, scoreboard header, dialog body, download window title | CFonts::DrawText / DrawLittleText |
| Chat lines, buttons, table rows, statics | the CFontWrapper vtable |
| Dialog body again, so it lands above the panel fill | CDialog::Draw |
| Spawn screen buttons, server dialog, download window list | the direct call sites of CDXUTDialog::OnRender |
| Death window names | the font level, by the shape of the calls |
| Object material text, license plate | the font level and the wrapper, drawn into the texture |
Nothing is keyed on one build's addresses. The three signatures are matched in .text; the
wrapper vtable is searched for (an eighteen slot table in .rdata whose slot 14 carries
the client's own cmp eax, 0x186A0 length guard), which is how the chat and the buttons are
reached on 0.3.7 as well; and the shadow/body decision uses the call shapes instead of
addresses - four black passes then the body, so the fifth call is the body even when it is
black.
Each panel's text is recorded while that panel draws and painted once its draw has
returned, because the client paints the translucent fill after the text it produced inside
it. CDXUTDialog::OnRender is the awkward one: it draws inside an open sprite batch, so its
entry point is left alone and its call sites are redirected to a stub that runs it first and
paints afterwards.
Text that renders into a texture is drawn after the sprite batch closes, which is the only moment where the texture is still the target and the batch is not open.
A tab only means two columns in TABLIST and TABLIST_HEADERS; there the client splits the
line itself and draws every cell at its own position. In the other four styles a tab is
expanded to client_text_tab spaces, which is what DT_EXPANDTABS does anyway.
CLIENT-TEXT.md has the hook points, every client_text_* key, the
measured offsets for all seven builds, and the approaches that were tried and do not work.
Servers with mixed code pages
Ta strona jest zbudowana z tego, co GitHub publikuje o repozytorium. samp.directory nie hostuje kodu. Zgłoś problem z tym wpisem