.\" SPDX-License-Identifier: MIT
.\"
.Dd August 1, 2026
.Dt RGBFIX 1
.Os
.Sh "نام (NAME)"
.Nm rgbfix
.Nd ابزار سرایند Game Boy و اصلاح‌کننده checksum
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl hjsVvw
.Op Fl C | c
.Op Fl \-color Ar when
.Op Fl f Ar fix_spec
.Op Fl i Ar game_id
.Op Fl k Ar licensee_str
.Op Fl L Ar logo_file
.Op Fl l Ar licensee_id
.Op Fl m Ar mbc_type
.Op Fl n Ar rom_version
.Op Fl o Ar out_file
.Op Fl p Ar pad_value
.Op Fl r Ar ram_size
.Op Fl t Ar title_str
.Op Fl W Ar warning
.Ar
.Sh "توضیحات (DESCRIPTION)"
برنامه
.Nm
هدرهای ایمیج‌های ROM گیم‌بوی (Game Boy) را که معمولاً توسط
.Xr rgblink 1
تولید شده‌اند تغییر می‌دهد، اگرچه با
.Em هر
ROM گیم‌بوی دیگری نیز کار خواهد کرد.
این برنامه همچنین سایر عملیات درستی‌سنجی مانند پدینگ (padding) را انجام می‌دهد.
.Nm
تنها فیلدهایی را تغییر می‌دهد که مقداری برای آن‌ها مشخص شده باشد.
به توسعه‌دهندگان توصیه می‌شود پیش از اجرای
.Nm ،
آن فیلدها را در کد منبع خود با بایت‌های 0x00 پر کنند، و فیلدهایی را که با
.Nm
مشخص نکرده‌اند از قبل مقداردهی کرده باشند.
.Sh "آرگومان‌ها (ARGUMENTS)"
.Nm
گزینه‌های معمول کوتاه و بلند مانند
.Fl V
و
.Fl -version
را می‌پذیرد.
گزینه‌های بعدی در خط فرمان، مقادیر تنظیم‌شده قبلی را بازنویسی (override) می‌کنند، مگر در مواردی که گزینه‌های تکراری به عنوان خطا در نظر گرفته شوند.
گزینه‌ها را می‌توان تا زمانی که سردرگم‌کننده نباشند به صورت مخفف نوشت:
.Fl \-ver
همان
.Fl \-version
است، اما
.Fl \-v
نامعتبر است زیرا می‌تواند به معنای
.Fl \-validate
نیز باشد.
.Pp
مگر در مواردی که خلاف آن ذکر شده باشد، ارسال
.Ql -
(یک خط تیره تکی) به عنوان نام فایل باعث می‌شود
.Nm
از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند.
برای لغو این رفتار و باز کردن فایلی در دایرکتوری جاری که نام واقعی آن
.Ql -
است، به جای آن
.Ql ./-
را ارسال کنید.
استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور منفرد ممکن است نتایج غیرمنتظره‌ای ایجاد کند.
.Pp
.Nm
مقدارهای دهدهی (decimal)، هگزادسیمال (hexadecimal)، هشت‌هشتی (octal) و دودویی (binary) را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد.
اعداد دهدهی به صورت معمول نوشته می‌شوند؛ اعداد هگزادسیمال باید دارای پیشوند
.Ql $
یا
.Ql 0x
باشند؛
اعداد هشت‌هشتی باید دارای پیشوند
.Ql &
یا
.Ql 0o
باشند؛
و اعداد دودویی باید دارای پیشوند
.Ql %
یا
.Ql 0b
باشند.
(پیشوندهای
.Ql $
و
.Ql &
احتمالاً نیاز به فرار (escaping) یا نقل‌قول (quoting) دارند تا توسط شل تفسیر نشوند.)
صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند.
برای مثال، تمامی این موارد معادل یکدیگرند:
.Ql 42 ,
.Ql 042 ,
.Ql 0x2A ,
.Ql 0X2A ,
.Ql 0x2a ,
.Ql &52 ,
.Ql 0o52 ,
.Ql 0O052 ,
.Ql 0b00101010 ,
.Ql 0B101010 .
.Pp
گزینه‌های زیر پذیرفته می‌شوند:
.Bl -tag -width Ds
.It Fl C , Fl \-color-only
تنظیم پرچم Game Boy Color\(enonly
.Pq Ad 0x143
روی 0xC0.
این گزینه در صورت تنظیم قبلی
.Fl c ،
آن را بازنویسی می‌کند.
.It Fl c , Fl \-color-compatible
تنظیم پرچم Game Boy Color\(encompatible:
.Pq Ad 0x143
روی 0x80.
این گزینه در صورت تنظیم قبلی
.Fl c ،
آن را بازنویسی می‌کند.
.It Fl \-color Ar when
تعیین زمان برجسته‌سازی پیام‌های هشدار و خطا با رنگ:
.Ql always ,
.Ql never
یا
.Ql auto .
مقدار
.Ql auto
بر اساس متغیرهای محیطی
.Ql Lk https://no-color.org NO_COLOR
یا
.Ql Lk https://force-color.org FORCE_COLOR ،
یا اینکه آیا خروجی به یک TTY ارسال می‌شود یا خیر، استفاده از رنگ‌ها را تعیین می‌کند.
.It Fl f Ar fix_spec , Fl \-fix-spec Ar fix_spec
اصلاح مقادیر خاصی از هدر که Game Boy درستی آن‌ها را بررسی می‌کند.
همچنین می‌توان با نوشتن معکوس دودویی (binary inverse) آنها، این مقادیر را عمداً تخریب کرد.
.Ar fix_spec
رشته‌ای است شامل هر ترکیبی از نویسه‌های زیر:
.Pp
.Bl -tag -compact -width xx
.It Cm l
اصلاح لوگوی Nintendo
.Pq Ad 0x104 Ns \(en Ns Ad 0x133 .
.It Cm L
تخریب لوگوی Nintendo.
.It Cm h
اصلاح چک‌سام هدر
.Pq Ad 0x14D .
.It Cm H
تخریب چک‌سام هدر.
.It Cm g
اصلاح چک‌سام سراسری (global checksum)
.Pq Ad 0x14E Ns \(en Ns Ad 0x14F .
.It Cm G
تخریب چک‌سام سراسری.
.El
.It Fl h , Fl \-help
چاپ متن راهنمای برنامه و خروج.
(اگر متغیر محیطی
.Dv COLUMNS
با مقداری غیرصفر تعریف شده باشد، متن راهنما مطابق با آن شکسته می‌شود؛ در غیر این صورت اگر خروجی به یک TTY باشد، مطابق با عرض پنجره کنسول شکسته خواهد شد.)
.It Fl i Ar game_id , Fl \-game-id Ar game_id
تنظیم رشته شناسه بازی (game ID)
.Pq Ad 0x13F Ns \(en Ns Ad 0x142
به رشته مشخص‌شده.
اگر طول آن بیش از ۴ نویسه باشد، بریده خواهد شد.
.It Fl j , Fl \-non-japanese
تنظیم پرچم منطقه غیرژاپنی (non-Japanese region)
.Pq Ad 0x14A
روی 0x01.
.It Fl k Ar licensee_str , Fl \-new-licensee Ar licensee_str
تنظیم رشته دارنده امتیاز جدید (new licensee)
.Pq Ad 0x144 Ns \(en Ns Ad 0x145
به رشته مشخص‌شده.
اگر طول آن بیش از ۲ نویسه باشد، بریده خواهد شد.
.It Fl L Ar logo_file , Fl \-logo Ar logo_file
مشخص کردن یک فایل لوگو برای استفاده به جای لوگوی رسمی Nintendo.
فایل باید شامل ۴۸ بایت از داده‌های تایل 1bpp باشد؛ تصویر منبع باید دارای عرض ۴۸ پیکسل و ارتفاع ۸ پیکسل باشد.
.It Fl l Ar licensee_id , Fl \-old-licensee Ar licensee_id
تنظیم کد دارنده امتیاز قدیمی (old licensee)
.Pq Ad 0x14B
به مقدار مشخص‌شده از 0 تا 0xFF.
این مقدار منسوخ شده است و در تمامی نرم‌افزارهای جدید باید روی 0x33 تنظیم شود.
.It Fl m Ar mbc_type , Fl \-mbc-type Ar mbc_type
تنظیم نوع MBC.Pq Ad 0x147
به یک مقدار داده‌شده از 0 تا 0xFF.
.Pp
این مقدار همچنین می‌تواند نام یک MBC باشد.
فهرست نام‌های پذیرفته‌شده را می‌توان با دادن
.Ql Cm help
یا
.Ql Cm list
به‌عنوان آرگومان به دست آورد.
هر میزانی از فاصله‌های خالی (فاصله و تب) در اطراف علامت‌های مثبت مجاز است، و ترتیب «مؤلفه‌ها» آزاد است، تا زمانی که نام MBC در ابتدا باشد.
ملاحظات ویژه‌ای برای نگاشت‌گر TPP1 وجود دارد؛ به بخش
.Sx TPP1
در زیر مراجعه کنید.
.It Fl n Ar rom_version , Fl \-rom-version Ar rom_version
تنظیم نسخهٔ ROM
.Pq Ad 0x14C
به یک مقدار داده‌شده از 0 تا 0xFF.
.It Fl o Ar out_file , Fl \-output Ar out_file
نوشتن تصویر ROM تغییریافته در فایل داده‌شده، یا '-' برای نوشتن در خروجی استاندارد.
در صورت عدم تعیین، فایل‌های ورودی درجا تغییر می‌یابند، یا در صورت خوانده شدن از ورودی استاندارد، در خروجی استاندارد نوشته می‌شوند.
.It Fl p Ar pad_value , Fl \-pad-value Ar pad_value
پد کردن تصویر ROM تا یک اندازهٔ معتبر با یک مقدار پد مشخص از 0 تا 255 (0xFF).
.Nm
به‌طور خودکار اندازه‌ای را از 32 KiB، 64 KiB، 128 KiB، ...، 8192 KiB انتخاب خواهد کرد.
بایت اندازهٔ کارتریج
.Pq Ad 0x148
برای بازتاب این اندازهٔ جدید تغییر خواهد کرد.
مقدار پد توصیه‌شده 0xFF است، تا سرعت نوشتن ROM روی تراشه‌های فلش افزایش یابد، و از «nop slide»ها به داخل VRAM جلوگیری شود.
.It Fl r Ar ram_size , Fl \-ram-size Ar ram_size
تنظیم اندازهٔ RAM
.Pq Ad 0x149
به یک مقدار داده‌شده از 0 تا 0xFF.
.It Fl s , Fl \-sgb-compatible
تنظیم پرچم SGB
.Pq Ad 0x146
روی 0x03.
این پرچم توسط SGB نادیده گرفته خواهد شد، مگر اینکه کد دارندهٔ مجوز قدیمی
.Pq Fl l
برابر 0x33 باشد!
.It Fl t Ar title , Fl \-title Ar title
تنظیم رشتهٔ عنوان
.Pq Ad 0x134 Ns \(en Ns Ad 0x143
به یک رشتهٔ داده‌شده.
اگر عنوان از بیشینهٔ طول طولانی‌تر باشد، کوتاه خواهد شد.
بیشینهٔ طول ۱۱ نویسه است اگر شناسهٔ بازی
.Pq Fl i
مشخص شده باشد، ۱۵ نویسه اگر پرچم CGB
.Fl ( c
یا
.Fl C )
مشخص شده باشد اما شناسهٔ بازی تعیین نشده باشد، و در غیر این صورت ۱۶ نویسه است.
.It Fl V , Fl \-version
چاپ نسخهٔ برنامه و خروج.
.It Fl v , Fl \-validate
معادل با
.Fl f Cm lhg .
.It Fl W Ar warning , Fl \-warning Ar warning
تنظیم پرچم هشدار
.Ar warning .
اگر
.Ar warning
یک پرچم هشدار ناشناخته باشد، یک پیام هشدار چاپ خواهد شد.
برای فهرستی از هشدارها به بخش
.Sx DIAGNOSTICS
مراجعه کنید.
.It Fl w
غیرفعال کردن تمام خروجی‌های هشدار، حتی زمانی که به خطا تبدیل شده باشند.
.It @ Ns Ar at_file
خواندن گزینه‌ها و آرگومان‌های بیشتر از یک فایل، به‌گونه‌ای که گویی محتویات آن در خط فرمان داده شده است.
آرگومان‌ها با فاصلهٔ خالی یا خطوط جدید از هم جدا می‌شوند.
خطوطی که با علامت هش
.Pq Ql #
شروع می‌شوند، کامنت در نظر گرفته شده و نادیده گرفته می‌شوند.
.Pp
هیچ پردازشی توسط پوسته انجام نمی‌شود، مانند بسط نویسهٔ عام یا بسط متغیر.
هیچ پشتیبانی‌ای برای گریز دادن یا نقل‌قول کردن فاصله‌های خالی جهت گنجاندن در آرگومان‌ها وجود ندارد.
عبارت استاندارد
.Ql --
برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند.
توجه داشته باشید که هرچند
.Ql --
می‌تواند
.Em درون
یک at-file استفاده شود، اما تنها پردازش گزینه‌ها را در همان at-file غیرفعال می‌کند و پردازش در دامنهٔ والد ادامه می‌یابد.
.El.Sh "خطاها (DIAGNOSTICS)"
هشدارها پیام‌های تشخیصی هستند که رفتارهای احتمالاً نادرستی را نشان می‌دهند که لزوماً فرایند اصلاح سرایند (header) را با مشکل مواجه نمی‌کنند.
گزینه‌های زیر نحوهٔ پردازش هشدارها را تغییر می‌دهند.
.Bl -tag -width Ds
.It Fl Werror
تبدیل تمام هشدارها به خطا.
این مورد را می‌توان با
.Fl Wno-error
نفی کرد تا از تبدیل همهٔ هشدارها به خطا جلوگیری شود.
.It Fl Werror=
تبدیل هشدار یا فراهشدار (meta warning) مشخص‌شده به خطا.
نام هشدار به آن افزوده می‌شود
.Pq مثال: Fl Werror=obsolete ,
و این هشدار به صورت ضمنی فعال شده و به خطا تبدیل می‌شود.
این مورد را می‌توان با
.Fl Wno-error=
نفی کرد تا از تبدیل یک هشدار مشخص به خطا جلوگیری شود، حتی اگر
.Fl Werror
اعمال شده باشد.
.El
.Pp
هشدارهای زیر هشدارهای
.Dq meta
هستند، که مجموعه‌ای از هشدارهای دیگر را فعال می‌کنند.
اگر یک هشدار خاص هم از طریق یک پرچم meta و هم یک پرچم خاص تغییر وضعیت دهد، پرچم خاص‌تر اولویت دارد.
موقعیت در خط فرمان به عنوان تعیین‌کننده عمل می‌کند و آخرین مورد اعمال خواهد شد.
.Bl -tag -width Ds
.It Fl Wall
هشدارهایی را فعال می‌کند که به احتمال زیاد نشان‌دهندهٔ خطا یا رفتار ناخواسته هستند و به سادگی قابل رفع می‌باشند.
.It Fl Weverything
به معنای واقعی کلمه همهٔ هشدارها را فعال می‌کند.
.El
.Pp
هشدارهای زیر پرچم‌های هشدار واقعی هستند؛ همراه با هر توضیح، پرچم هشدار مربوطه نیز آورده شده است.
توجه داشته باشید که هر یک از این پرچم‌ها دارای یک حالت نفی نیز هستند (برای مثال،
.Fl Wobsolete
هشداری را فعال می‌کند که
.Fl Wno-obsolete
غیرفعال می‌سازد؛ و
.Fl Wall
هر هشداری را که
.Fl Wno-all
غیرفعال می‌کند، فعال می‌سازد).
در اینجا تنها پرچم غیرپیش‌فرض ذکر شده است.
با نادیده گرفتن پیشوند
.Dq no-
ورودی‌ها به ترتیب الفبایی فهرست شده‌اند.
.Bl -tag -width Ds
.It Fl Wno-mbc
هشدار هنگام وجود ناسازگاری یا نکات قابل‌توجه درباره نوع MBC مشخص‌شده.
.It Fl Wno-obsolete
هشدار هنگام مواجهه با قابلیت‌های منسوخی که دیگر پشتیبانی نمی‌شوند و ممکن است بعداً حذف شوند.
.It Fl Wno-overwrite
هشدار هنگام بازنویسی بایت‌های غیرصفر متفاوت در سرایند.
.It Fl Wno-sgb
هشدار هنگام تداخل پرچم SGB
.Pq Fl s
با کد مجوزدهندهٔ قدیمی
.Pq Fl l .
.It Fl Wno-truncation
هشدار هنگام کوتاه کردن مقادیر برای جا شدن در فضای موجود.
.El
.Sh "مثال‌ها (EXAMPLES)"
بیشتر مقادیر موجود در سرایند ROM برای خود کنسول اهمیتی ندارند و به هر حال بیشتر آن‌ها به‌ندرت مفید واقع می‌شوند.
حداقل ملزومات برای یک برنامهٔ قابل اجرا، چک‌سام سرایند، لوگوی Nintendo و (در صورت نیاز) پرچم‌های CGB/SGB هستند.
همچنین پر کردن (padding) اندازهٔ تصویر تا یک اندازهٔ معتبر ایدهٔ خوبی است
.Pq Do معتبر Dc به معنای توانی از ۲، ضرب در 32 KiB .
.Pp
دستور زیر یک بازی معمولی و غیررنگی Game Boy را بدون بررسی اندازهٔ معتبر می‌سازد:
.Pp
.D1 $ rgbfix -v foo.gb
.Pp
دستور زیر یک بازی با قابلیت SGB و رنگی با عنوان
.Dq foobar
می‌سازد و آن را تا یک اندازهٔ معتبر پر می‌کند.
.Pq خود Game Boy از عنوان استفاده نمی‌کند، اما برخی شبیه‌سازها یا مدیران ROM از آن استفاده می‌کنند.
.Pp
.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
.Pp
دستور زیر سرایند بازی
.Dq Survival Kids
را بدون چک‌سام سراسری تکثیر می‌کند:
.Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc.Sh TPP1
TPP1 یک نگاشت‌گر (mapper) دست‌ساز (homebrew) است که به‌عنوان یک ابرمجموعه تابعی از MBCهای سنتی و متداول طراحی شده و امکان استفاده از اندازه‌های بزرگ‌تر ROM و RAM را همراه با دیگر قابلیت‌های سخت‌افزاری فراهم می‌کند.
مشخصات فنی آن و همچنین منابع بیشتر را می‌توان به‌صورت آنلاین در
.Lk https://github.com/aaaaaa123456789/tpp1
یافت.
.Ss "نام MBC"
نام MBC برای TPP1 پیچیده‌تر از نگاشت‌گرهای استاندارد است.
باید پس از آن شماره ویرایش، به فرم
.Ql major.minor
بیاید، که در آن هر دو مقدار
.Ql major
و
.Ql minor
اعداد صحیح ده‌دهی ۸ بیتی هستند.
می‌تواند هر تعداد فاصله یا زیرخط (underscore) بین
.Ql TPP1
و شماره ویرایش وجود داشته باشد.
.Nm
تنها از ویرایش‌های 1.x پشتیبانی می‌کند و هر مقدار دیگری را رد خواهد کرد.
.Pp
همانند سایر نگاشت‌گرها، نام می‌تواند با فهرستی از قابلیت‌های اختیاری که با
.Ql +
از هم جدا شده‌اند دنبال شود؛ با این حال،
.Ql RAM
نباید مشخص شود، زیرا نگاشت‌گر TPP1 در صورت تعیین اندازه‌ای غیرصفر برای RAM، آن را به‌طور ضمنی درخواست می‌کند.
بنابراین،
.Nm
ویژگی
.Ql RAM
را در یک نگاشت‌گر TPP1 نادیده خواهد گرفت.
.Ss "ملاحظات ویژه"
TPP1 بایت موجود در آدرس
.Ad 0x14A
را که معمولاً نشان‌دهنده منطقه مقصد است
.Pq گزینه Fl j را ببینید
با یکی از سه بایت شناسایی خود بازنویسی می‌کند.
بنابراین،
.Nm
در صورت استفاده همگام با TPP1، در مورد
.Fl j
هشدار داده و آن را نادیده خواهد گرفت.
.Sh "گزارش باگ‌ها (BUGS)"
لطفاً باگ‌ها یا اشتباهات موجود در این مستندات را در
.Lk https://github.com/gbdev/rgbds/issues GitHub
گزارش دهید.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbgfx 1 ,
.Xr gbz80 7 ,
.Xr rgbds 7
.Sh "تاریخچه (HISTORY)"
.Nm
در ابتدا توسط
.An Carsten S\(/orensen
به‌عنوان یک برنامه مستقل به نام GBFix نوشته شد، که سپس در ASMotor قرار گرفت و بعدها در RGBDS توسط
.An Justin Lloyd
مجدداً بسته‌بندی شد.
این پروژه اکنون توسط چندین مشارکت‌کننده در
.Lk https://github.com/gbdev/rgbds
نگه‌داری می‌شود.