Ports para o Arch R
Bibliotecas, APIs gráficas, drivers de GPU, caminhos e ambiente de execução para quem cria ou adapta ports de jogos para o Arch R
Esta página é para quem cria um port para o Arch R ou adapta um port do PortMaster a ele. Ela descreve o Arch R 3.1.0 no RK3326 (R36S e clones, GPU Mali-G31). Cada caminho e variável daqui foi lido no código do Arch R ou conferido num R36S. Onde algo não pôde ser conferido, a página diz.
O mesmo material existe como skill para assistentes de código, a archr-ports-dev: com ela instalada, o Claude Code (ou outro assistente que leia Agent Skills) adapta um port, descobre por que um falha ou prepara um para o PortMaster com estas regras. Veja Skills de IA.
A plataforma numa tabela
| CPU | Rockchip RK3326, 4 × Cortex-A35, aarch64 |
| Userland | Arch Linux ARM, glibc 2.40, 64 bits em /usr/lib, 32 bits armhf em /usr/lib32 |
| Loader de 32 bits | /lib/ld-linux-armhf.so.3 → /usr/lib32/ld-linux-armhf.so.3 |
| GPU | Mali-G31 MC1 (Bifrost) |
| Tela | sway (Wayland), WAYLAND_DISPLAY=wayland-1, XDG_RUNTIME_DIR=/var/run/0-runtime-dir |
| Resolução | 640×480 no R36S (DISPLAY_WIDTH/DISPLAY_HEIGHT do PortMaster) |
| Áudio | PipeWire com pipewire-pulse; SDL_AUDIODRIVER=pulseaudio |
| Usuário | tudo, ports incluídos, roda como root; HOME=/storage |
| Pasta de ports | /storage/roms/ports (/roms é um link para /storage/roms) |
/lib é um link para /usr/lib. O lado de 32 bits é achado por /etc/ld.so.conf.d/arm-lib32.conf, que lista /usr/lib32. O cache de bibliotecas fica em /storage/.cache/ld.so.cache e é refeito no boot sempre que o driver de GPU muda.
Dois drivers de GPU
O usuário escolhe um em Configurações › Sistema › Driver de GPU, gravado como gpu.driver em /storage/.config/system/configs/system.cfg. A troca vale depois de reiniciar. O padrão é libmali.
libmali (padrão) | panfrost | |
|---|---|---|
| Módulo do kernel | mali_kbase | panfrost |
| Espaço de usuário | blob da ARM libmali.so.1 (g24p0, build Wayland + GBM) | Mesa 26.2.7 |
| OpenGL ES | 1.1, 2.0, 3.x (o blob diz 3.2) | até 3.1 |
| OpenGL de desktop | não tem (libGL.so fica escondida) | 3.1 |
| Vulkan | não tem | 1.0 pelo PanVK |
| OpenCL | dentro de libmali.so.1, veja OpenCL | não tem |
| EGL / GBM | da libmali | do Mesa |
No boot, /usr/bin/gpudriver --start carrega o módulo e põe as bibliotecas certas no lugar com bind mounts. Nenhum nome de arquivo muda, então um port linka contra os mesmos nomes nos dois drivers.
O que a libmali faz no boot
- Cada arquivo de
/usr/lib/malie/usr/lib32/malié montado (bind) sobre o arquivo de mesmo nome uma pasta acima:libEGL.so.1,libGLESv1_CM.so.1,libGLESv2.so.2,libgbm.so.1,libwayland-egl.so.1(e os links.so). Essas bibliotecas pequenas vêm do pacotelibmalie repassam as chamadas paralibmali.so.1por meio delibmali-hook.so.1. - O SDL2 só GLES de
/usr/lib/glesonlye/usr/lib32/glesonlyé montado sobrelibSDL2-2.0.so.0.3200.10. Esse SDL2 foi compilado sem OpenGL de desktop:SDL_GL_*com perfil de compatibilidade ou core falha, e perfil ES funciona. /dev/nullé montado sobre/usr/lib/libGL.soe/usr/lib32/libGL.so, para nada carregar o GL do Mesa por engano./dev/nullé montado sobre/usr/share/vulkan/icd.d/panfrost_icd.*.json, então o loader do Vulkan não acha driver.
O que o panfrost faz no boot
Nenhuma das montagens acima. libEGL, libGLESv2 e libgbm do Mesa, a libGL.so.1 da libglvnd e o ICD do PanVK aparecem nos lugares normais. A variável PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1 é exportada para todos os processos (veja Vulkan).
Quando o pacman atualiza um pacote gráfico, os hooks dele (archr-gpu-bind unbind|bind e archr-sdl-bind unbind|bind) tiram as montagens e as põem de volta sobre os arquivos novos. Um port nunca precisa mexer nessas montagens.
Onde ficam as bibliotecas
Caminhos de 64 bits primeiro, de 32 bits depois.
| Biblioteca | Arquivo | libmali | panfrost |
|---|---|---|---|
| EGL | /usr/lib/libEGL.so.1, /usr/lib32/libEGL.so.1 | libmali (montada) | libglvnd → libEGL_mesa.so.0 |
| GLES 2/3 | /usr/lib/libGLESv2.so.2, /usr/lib32/libGLESv2.so.2 | libmali (montada) | libglvnd → Mesa |
| GLES 1 | /usr/lib/libGLESv1_CM.so.1, /usr/lib32/… | libmali (montada) | libglvnd → Mesa |
| GBM | /usr/lib/libgbm.so.1, /usr/lib32/libgbm.so.1 | libmali (montada) | Mesa |
| wayland-egl | /usr/lib/libwayland-egl.so.1, /usr/lib32/… | libmali (montada) | wayland |
| GL de desktop | /usr/lib/libGL.so.1, libOpenGL.so.0, libGLX.so.0; o mesmo em /usr/lib32 | libGL.so é /dev/null | libglvnd → Mesa |
| DRI do Mesa | /usr/lib/dri/panfrost_dri.so, /usr/lib32/dri/panfrost_dri.so | sem uso | em uso |
| Loader Vulkan | /usr/lib/libvulkan.so.1 (só 64 bits) | presente, sem dispositivo | presente |
| ICD Vulkan | /usr/share/vulkan/icd.d/panfrost_icd.*.json → /usr/lib/libvulkan_panfrost.so | mascarado com /dev/null | ativo |
| A própria libmali | /usr/lib/libmali.so.1, /usr/lib32/libmali.so.1 | em uso | presente, inútil (sem /dev/mali0) |
| SDL2 | /usr/lib/libSDL2-2.0.so.0, /usr/lib32/libSDL2-2.0.so.0 (2.32.10) | build só GLES (montado) | build completo |
Não existe Vulkan de 32 bits: /usr/lib32 não tem libvulkan.so.1. Um port Vulkan precisa ser de 64 bits.
Só o SDL2 completo de 64 bits (/usr/lib/libSDL2-2.0.so.0 no panfrost) tem suporte a Vulkan. SDL_Vulkan_LoadLibrary falha no build só GLES e nos builds de 32 bits.
Caminhos no estilo Debian
Ports feitos para ArkOS ou dArkOS costumam citar as pastas multiarch do Debian. No Arch R elas são links:
/usr/lib/aarch64-linux-gnu -> . (ou seja, /usr/lib)
/usr/lib/arm-linux-gnueabihf -> ../lib32/lib/aarch64-linux-gnu e /lib/arm-linux-gnueabihf também funcionam, porque /lib é /usr/lib. LD_PRELOAD=/usr/lib/arm-linux-gnueabihf/libSDL2-2.0.so.0 cai no SDL2 de 32 bits.
Bibliotecas antigas do Debian
/usr/lib/compat guarda sonames da época do Debian 11 que ports esperam e o Arch não tem mais (libavcodec.so.58, libcrypto.so.1.1, libjpeg.so.62, libx264.so.160, libx265.so.192 e outras). O get_controls do PortMaster define LD_LIBRARY_PATH=/usr/lib/compat/ (a variável clibs). Liste a pasta no console para ver tudo; um port que precisa de uma biblioteca que não está lá deve trazê-la na própria pasta libs.aarch64 ou libs.armhf.
OpenGL, OpenGL ES e gl4es
Escreva para OpenGL ES 2.0 ou 3.0 via EGL. Isso roda nos dois drivers sem pedir nada ao usuário.
OpenGL de desktop só existe no panfrost (o Mesa informa 3.1 Mesa, compatibilidade e core). Na libmali, libGL.so é /dev/null, então um programa linkado contra libGL.so.1 não abre, ou não ganha contexto do SDL.
Ports que precisam de GL de desktop costumam trazer o gl4es, que traduz GL 2.1 para GLES 2. Os ports do PortMaster carregam um arquivo libgl_<CFW>.txt com os ajustes dele, e o Arch R fornece libgl_ArchR.txt em /roms/ports/PortMaster/:
export LIBGL_ES=2
export LIBGL_GL=21
if [ -d /sys/module/panfrost ]; then
export LIBGL_FB=3 # PBuffer: no panfrost o backend GBM não desenha nada sob o sway
else
export LIBGL_FB=4 # GBM
fi
[ -e /dev/dri/card0 ] || export LIBGL_FB=2
# depois põe $PWD/gl4es[.$DEVICE_ARCH] e $PWD/libs[.$DEVICE_ARCH] na frente do LD_LIBRARY_PATHCarregue-o de dentro da pasta do port, depois de cd "$GAMEDIR", porque ele usa $PWD.
O mod_ArchR.txt também exporta LIBGL_DRIVERS_PATH=/usr/lib32/dri:/usr/lib/dri para todo port.
Ajustes do Mesa exportados para todos os processos por /etc/profile.d/041-panfrost: MESA_NO_ERROR=1 (sem checagem de erro de GL), MESA_SHADER_CACHE_DIR=/var/cache/mesa, MESA_SHADER_CACHE_MAX_SIZE=128MB. Um port que depende de glGetError no panfrost precisa tirar o MESA_NO_ERROR por conta própria.
Sistema de janelas: Wayland, não KMS
O sway segura a tela o tempo todo em que um jogo roda. Um port tem de abrir uma janela Wayland (ou passar pelo Xwayland se precisar de X11; isso não foi conferido nesta versão). Saída direta por KMS/DRM não consegue a tela.
SDL_VIDEODRIVER=waylandé exportada para todo o sistema.- O SDL2 do Arch R tem um patch:
SDL_VIDEODRIVER=kmsdrm, que muitos ports do ArkOS definem, cai na ordem normal (Wayland primeiro) quandoWAYLAND_DISPLAYexiste ou quando o KMSDRM não sobe.ARCHR_SDL_KMSDRM=1mantém o KMSDRM forçado, o que só faz sentido fora do sway. - EGL no Wayland funciona nos dois drivers: a libmali é o build
wayland-gbme exportawl_egl_window_create. - A janela fica em tela cheia pelo
pm_platform_helperdomod_ArchR.txt, que chamasway_fullscreencom o nome do programa (oapp_iddo sway). Chamepm_platform_helper "$GAMEDIR/<binário>"antes de iniciar o jogo, como os ports do PortMaster já fazem, ou use umapp_idigual ao nome do binário. - No panfrost existem
/dev/dri/card0,/dev/dri/card1e/dev/dri/renderD128. Na libmali o nó da GPU é/dev/mali0.
MALI_WAYLAND_AFBC=0 e MALI_SCHED_RT_THREAD_PRIORITY=95 são exportadas para a libmali.
Vulkan
O Vulkan está disponível quando o driver de GPU é o panfrost. É o PanVK do Mesa no Mali-G31.
| Loader | /usr/lib/libvulkan.so.1 (vulkan-loader 1.4.354), só 64 bits |
| ICD | /usr/share/vulkan/icd.d/panfrost_icd.armv8-a+crc+fp+simd.json → /usr/lib/libvulkan_panfrost.so |
| Dispositivo | Mali-G31 MC1, driverName = panvk, driverID = DRIVER_ID_MESA_PANVK, vendor 0x13b5 |
| Versão da API | 1.0 (apiVersion = 1.0.354); versão da instância 1.4.354 |
| Conformidade | nenhuma (conformanceVersion = 0.0.0.0) |
| WSI | VK_KHR_wayland_surface, VK_KHR_display, VK_KHR_xcb_surface, VK_KHR_xlib_surface |
| Camada implícita | VK_LAYER_MANGOHUD_overlay_aarch64 |
O PanVK só anuncia 1.1 ou mais em GPUs Mali v10 ou mais novas; o G31 é v7 e fica no 1.0. Confira cada extensão que usar; não conte com o que o Vulkan 1.1 garante. Testado num R36S: vkcube, vkmark (cenas com textura tiveram falhas de job na GPU), PPSSPP e RetroArch no renderizador Vulkan.
A variável
No Mali v7, o PanVK recusa criar o dispositivo sem PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1. Sem ela o loader mostra panvk is not well-tested on v7 e vkEnumeratePhysicalDevices não devolve GPU. O /etc/profile.d/041-panfrost a exporta sempre que /sys/module/panfrost existe, então com o panfrost ativo todo processo iniciado pelo /etc/profile a tem, ports incluídos. Não a defina você; se ela não estiver lá, o Vulkan não deve ser usado.
MESA_VK_VERSION_OVERRIDE faz o PanVK anunciar uma versão de API maior. Os recursos dessa versão não existem; use só para experimentos.
Com a libmali
Não há dispositivo Vulkan. O loader está instalado, mas o ICD do panfrost é /dev/null, e a libmali do G31 não tem driver Vulkan. vkCreateInstance funciona e vkEnumeratePhysicalDevices devolve zero dispositivos.
Como detectar e cair para GLES
No código, siga a ordem de sempre e trate qualquer falha como "sem Vulkan":
dlopen("libvulkan.so.1")(ouSDL_Vulkan_LoadLibrary(NULL)).vkCreateInstancecomVK_KHR_surfaceeVK_KHR_wayland_surface.vkEnumeratePhysicalDevicesdevolve pelo menos um dispositivo.- O dispositivo tem as extensões e formatos de que você precisa.
Se algum passo falhar, inicie o renderizador GLES. Um port que só tem renderizador Vulkan deve declarar que precisa do panfrost (próxima seção), para o usuário receber a oferta de troca em vez de um travamento.
Num script de início:
if [ -d /sys/module/panfrost ] && vulkaninfo --summary >/dev/null 2>&1; then
RENDERER=vulkan
else
RENDERER=gles
fivulkaninfo sai com 0 quando acha um dispositivo e com 1 quando não acha (conferido no R36S com e sem a variável).
Emuladores
Os emuladores rodam em GLES por padrão; Configurações › Jogos › Renderizador escolhe GLES ou Vulkan por sistema (RetroArch video_driver = vulkan, o backend Vulkan do PPSSPP e do Flycast standalone). Na libmali a escolha de Vulkan cai para GL. Veja Driver de GPU. Essa opção vale só para emuladores; um port escolhe o próprio renderizador como acima.
OpenCL
O que existe no sistema:
/etc/OpenCL/vendors/mali.icd(do pacotelibmali) apontalibMaliOpenCL.so.1.libMaliOpenCL.so.1só existe em/usr/lib/malie/usr/lib32/mali. Ao contrário das bibliotecas de GL, não há arquivo com esse nome em/usr/lib, então as montagens do boot não a põem no caminho de bibliotecas.- A própria
libmali.so.1exporta a API OpenCL (clGetPlatformIDs,clIcdGetPlatformIDsKHRe outros 152 símboloscl*). - Não há loader de ICD (
libOpenCL.so.1) no sistema, e o Mesa é compilado sem Rusticl.
Então OpenCL só é possível na libmali, e só linkando libmali.so.1 direto ou com dlopen("/usr/lib/mali/libMaliOpenCL.so.1"). Um port que quer um loader de ICD precisa trazer a própria libOpenCL.so.1; o loader lê o mali.icd e depois precisa de /usr/lib/mali no LD_LIBRARY_PATH para achar libMaliOpenCL.so.1. No panfrost não há OpenCL nenhum (/dev/mali0 não existe).
O Arch R não testou nenhum programa OpenCL no R36S. Leia esta seção como a disposição dos arquivos, não como garantia de que kernels OpenCL rodam.
Como o port avisa que precisa do panfrost
Quando um port só roda no panfrost (GL de desktop sem gl4es, só Vulkan, ou travamento dentro da libmali), declare isso. O archr-launcher confere quando o usuário inicia o port pela lista de Ports e o driver configurado é libmali. Em vez de abrir o jogo, ele mostra:
<título>precisa do driver panfrost Este jogo usa OpenGL, que o driver de GPU atual (libmali) não tem. A troca vale para todo o sistema e o console reinicia. Para voltar: Configurações › Sistema › Driver de GPU.
A (Trocar e reiniciar) grava gpu.driver=panfrost pelo gpudriver e reinicia. B cancela e o port não abre. No panfrost o port abre normalmente.
A conferência só funciona num script com o cabeçalho do PortMaster nas 10 primeiras linhas:
#!/bin/bash
# PORTMASTER: meujogo.zip, Meu Jogo.shO nome antes da vírgula (meujogo.zip) é o nome do pacote. O port precisa do panfrost quando qualquer um destes vale:
-
O
port.jsondele diz (preferido). O launcher lê cada<pasta de ports>/*/port.jsonao lado do script, pega o que tem"name"igual ao nome do pacote (sem diferenciar maiúsculas) e procura"opengl"emattr.reqs(sem diferenciar maiúsculas):{ "version": 4, "name": "meujogo.zip", "items": ["Meu Jogo.sh", "meujogo/"], "attr": { "title": "Meu Jogo", "reqs": ["opengl"] } }É o campo do próprio PortMaster, então o mesmo
port.jsonserve em outros sistemas. Ponha oport.jsonna pasta do port (/storage/roms/ports/meujogo/port.json), como o PortMaster instala. -
O pacote está na lista do Arch R,
/usr/share/archr/portmaster/panfrost.txt: um nome de pacote por linha,#começa comentário, sem diferenciar maiúsculas. O arquivo é do pacote do sistema (fonte:projects/ArchR/packages/apps/portmaster/share/panfrost.txtno repositório da distribuição) e um update o substitui, então não o edite no console. Ele serve para ports do catálogo que falham na libmali mas cujoport.jsonnão diz isso. Para incluir um, abra uma issue ou um pull request em archr-linux/Arch-R.
A pergunta não aparece quando o port é iniciado de outro jeito (pelo app do PortMaster, por um script, por SSH). Um port que precisa do panfrost deve conferir o driver por conta própria e mostrar uma mensagem clara.
O aviso fala em "OpenGL" para todo port da lista, inclusive os que só usam Vulkan.
Como saber qual driver está ativo
Use o estado do kernel, que mostra o boot atual:
if [ -d /sys/module/panfrost ]; then
GPU=panfrost
elif [ -e /dev/mali0 ]; then
GPU=libmali
else
GPU=none # nenhum dos dois ligado: renderização por software
fi/sys/bus/platform/drivers/panfrost/ff400000.gpu também existe quando o panfrost está ligado.
gpudriver sem argumento imprime o driver configurado (gpu.driver). Ele pode ser diferente do que está rodando: depois de uma troca que espera reiniciar, ou por um boot depois de uma sonda que falhou. Nunca chame gpudriver panfrost ou gpudriver libmali de um port; isso muda a configuração do usuário para o próximo boot.
Num programa, a string de GL também diz: GL_RENDERER é Mali-G31 MC1 (Panfrost) no Mesa.
Ambiente de execução
Os ports são iniciados pelo runemu.sh como /usr/bin/bash "<script>", presos aos núcleos de CPU escolhidos para o jogo, com a saída em /var/log/exec.log. Antes de rodar o script ele:
- confere se os arquivos do PortMaster em
/roms/ports/PortMasterbatem com os do sistema (control.txt,mod_ArchR.txt,libgl_ArchR.txt) e os renova se não baterem; - liga o bit de execução no script, e nos arquivos ELF e scripts
#!da pasta do port (até 4 níveis) e dePortMaster/que não o tenham; - confere os runtimes de
attr.runtimenoport.json(ouruntime="…"no script), baixa o que faltar se houver rede, e se não houver recusa iniciar com uma mensagem; - desfaz bind mounts velhos deixados por ports que foram apagados.
Extensões aceitas na lista de Ports: .sh e .appimage.
Variáveis do control.txt do PortMaster (valores num R36S)
| Variável | Valor |
|---|---|
controlfolder | /roms/ports/PortMaster |
directory | roms (run/archr/roms2 quando o port está no segundo cartão) |
CFW_NAME | ArchR (do NAME em /etc/os-release) |
CFW_VERSION | a data do build, como 20261105 |
DEVICE_NAME | R36S |
DEVICE_CPU | RK3326 |
DEVICE_ARCH | aarch64 |
DEVICE_HAS_ARMHF, DEVICE_HAS_AARCH64 | Y |
DEVICE_HAS_X86, DEVICE_HAS_X86_64 | N |
DEVICE_RAM | 1 |
DISPLAY_WIDTH × DISPLAY_HEIGHT | 640 × 480 |
ASPECT_X:ASPECT_Y | 4:3 |
ANALOG_STICKS | 2 |
LOWRES | Y |
param_device | ogs |
ESUDO | vazio (tudo já roda como root) |
GPTOKEYB | /roms/ports/PortMaster/gptokeyb -1 |
GPTOKEYB2 | env LD_PRELOAD=/roms/ports/PortMaster/libinterpose.aarch64.so /roms/ports/PortMaster/gptokeyb2 -1 |
clibs | /usr/lib/compat/ |
SDLDBUSERFILE | /storage/.config/SDL-GameControllerDB/gamecontrollerdb.txt |
GODOT_OPTS | --resolution 640x480 -f (GODOT2_OPTS: -r 640x480 -f) |
O get_controls grava o mapeamento do controle em /tmp/gamecontrollerdb.txt, exporta SDL_GAMECONTROLLERCONFIG_FILE apontando para ele, preenche sdl_controllerconfig com o conteúdo e define LD_LIBRARY_PATH=/usr/lib/compat/.
Variáveis do /etc/profile (todos os processos)
HW_DEVICE=RK3326, QUIRK_DEVICE (o modelo do device tree, aqui Game Console R36S), UI_SERVICE, WAYLAND_DISPLAY, XDG_RUNTIME_DIR, SDL_VIDEODRIVER=wayland, SDL_AUDIODRIVER=pulseaudio, DISPLAY=:0.0, as variáveis do Mesa acima e, no panfrost, PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1. PAN_MESA_DEBUG=forcepack só é definida quando o usuário liga a opção forcepack para aquele sistema ou jogo.
Início padrão de um script
#!/bin/bash
# PORTMASTER: meujogo.zip, Meu Jogo.sh
XDG_DATA_HOME=${XDG_DATA_HOME:-$HOME/.local/share}
if [ -d "/opt/system/Tools/PortMaster/" ]; then
controlfolder="/opt/system/Tools/PortMaster"
elif [ -d "/opt/tools/PortMaster/" ]; then
controlfolder="/opt/tools/PortMaster"
elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
controlfolder="$XDG_DATA_HOME/PortMaster"
else
controlfolder="/roms/ports/PortMaster"
fi
source $controlfolder/control.txt
[ -f "${controlfolder}/mod_${CFW_NAME}.txt" ] && source "${controlfolder}/mod_${CFW_NAME}.txt"
get_controls
GAMEDIR="/$directory/ports/meujogo"
cd "$GAMEDIR"No Arch R, controlfolder termina como /roms/ports/PortMaster e o mod_ArchR.txt é carregado.
Ports de 32 bits
Binários armhf de 32 bits rodam direto com as bibliotecas de /usr/lib32 (Mesa e libmali têm builds de 32 bits, e as montagens cobrem /usr/lib32 também). Defina PORT_32BIT="Y" antes de carregar o mod_ArchR.txt, que então exporta SPA_PLUGIN_DIR=/usr/lib32/spa-0.2 e PIPEWIRE_MODULE_DIR=/usr/lib32/pipewire-0.3/ para clientes PipeWire de 32 bits acharem seus plugins. libpulse.so.0, libasound.so.2 e libpipewire-0.3.so.0 de 32 bits estão instaladas. Não há Vulkan de 32 bits.
Áudio
O PipeWire roda com pipewire-pulse e WirePlumber. O socket do PulseAudio é /var/run/0-runtime-dir/pulse/native. O SDL usa o backend PulseAudio (SDL_AUDIODRIVER=pulseaudio). Programas ALSA veem uma placa, rk817int. Use SDL ou PulseAudio; abrir o dispositivo ALSA direto disputa com o PipeWire.
Entrada
O controle embutido é r36s_Gamepad (driver odroidgo3-joypad, /dev/input/by-path/platform-odroidgo3-joypad-event-joystick). Use a API GameController do SDL com o mapeamento que o get_controls prepara. Para um jogo que só lê teclado e mouse, rode $GPTOKEYB "<binário>" -c "<arquivo>.gptk" & (ou $GPTOKEYB2); /dev/uinput tem escrita para todos. O oga_controls dos ports antigos também está em PortMaster/, e o control.txt troca param_device para ogs no R36S para ele achar o caminho certo do joypad.
Arquivos e saves
| Caminho | Uso |
|---|---|
/storage/roms/ports/<Nome>.sh | o script que aparece na lista de Ports |
/storage/roms/ports/<nome>/ | os arquivos do port (GAMEDIR), incluindo o port.json |
/storage/roms/ports/PortMaster/ | o PortMaster, control.txt, mod_ArchR.txt, libgl_ArchR.txt, runtimes em libs/ |
/storage/.config/PortMaster/ | as cópias de onde os arquivos do PortMaster são renovados |
/storage ($HOME) | ~/.config, ~/.local/share e pastas com ponto que o jogo grava |
/var/log/exec.log | a saída do último início |
/storage/.config/gpudriver.log | o que a troca de driver fez no boot |
/storage é ext4, então permissões e links simbólicos funcionam. Guarde os saves dentro do GAMEDIR (o bind_directories do PortMaster faz isso) para eles irem junto quando o port for copiado ou apagado.
Empacotamento para o PortMaster
Siga as regras de empacotamento do próprio PortMaster; o Arch R não pede nada além delas:
- o script com o cabeçalho
# PORTMASTER:e o início padrão acima; - a pasta do port com
port.json, preenchendoattr.reqs("opengl"quando precisa do panfrost),attr.arch(aarch64,armhf) eattr.runtime; - bibliotecas que o sistema não tem em
libs.aarch64/libs.armhf, e o gl4es emgl4es.aarch64/gl4es.armhfquando usado; pm_platform_helperantes do jogo começar,pm_finishdepois que ele termina.
Não traga libEGL, libGLES*, libgbm, libGL, libwayland-egl, libvulkan nem JSON de ICD. Elas têm de ser as do sistema, senão o programa fala com o driver errado.
Lista de teste no console
Por SSH (root, senha archr):
cat /etc/os-releaseegpudriver;ls -d /sys/module/panfrost /dev/mali0para ver qual driver está rodando.file <binário>, depoisldd <binário> | grep "not found"para um binário de 64 bits. Para um de 32 bits olddrespondenot a dynamic executable; liste as bibliotecas comreadelf -d <binário> | grep NEEDEDe procure cada uma em/usr/lib32e nolibs.armhfdo port.- Inicie o port pela lista de Ports, não pelo shell, para o
runemu.she a conferência do panfrost rodarem. Leia/var/log/exec.log. - Na libmali: ele abre, ou a pergunta do panfrost aparece quando deveria?
- No panfrost: o mesmo teste. Se usa Vulkan,
vulkaninfo --summarytem de listarMali-G31 MC1. - Controles, som, saída de volta para o launcher, um segundo início (saves mantidos).
- Copie o port de um PC pelo Samba uma vez, para ver que ele não depende de permissões que a cópia perde.
Cada troca de driver pede um reinício: Configurações › Sistema › Driver de GPU.
Problemas comuns
| Sintoma | Causa e correção |
|---|---|
Permission denied no binário | o bit de execução se perdeu numa cópia. O runemu.sh o devolve para arquivos ELF e #! quando o port é iniciado pela lista de Ports; pelo shell, use chmod +x |
libGL.so.1: cannot open shared object file, ou o SDL não cria contexto GL | a libmali não tem GL de desktop. Use GLES, traga o gl4es ou declare o panfrost |
kmsdrm not available | o sway segura a tela. Tire o SDL_VIDEODRIVER=kmsdrm; o SDL2 do Arch R já cai para Wayland |
vkEnumeratePhysicalDevices não devolve GPU | o driver é a libmali, ou PAN_I_WANT_A_BROKEN_VULKAN_DRIVER foi apagada. Caia para GLES |
um programa de 32 bits não acha libvulkan.so.1 | não existe Vulkan de 32 bits |
falta uma biblioteca em /usr/lib/aarch64-linux-gnu/ ou /usr/lib/arm-linux-gnueabihf/ | as pastas existem como links; quem falta é a biblioteca. Traga-a ou confira /usr/lib/compat |
falta um soname antigo (libcrypto.so.1.1, libavcodec.so.58) | chame get_controls (ele põe /usr/lib/compat no LD_LIBRARY_PATH) ou traga a biblioteca |
| tela preta com gl4es no panfrost | use o libgl_ArchR.txt, que define LIBGL_FB=3 no panfrost |
| a janela não fica em tela cheia | chame pm_platform_helper com o caminho do binário, ou faça o app_id igual ao nome do binário |
| o jogo não consegue gravar | HOME é /storage; confira os binds do port em /proc/self/mountinfo |
Veja também Driver de GPU e PortMaster.
Criar módulos
Referência dos módulos do archr-launcher (API 2 a 4) - modelo de execução, module.toml, permissões, pontos de extensão, protocolo JSON-RPC, Loja de módulos e dois exemplos.
Skills de IA
Instale as skills do ArchR para que o Claude Code ou outro assistente de código crie temas, módulos e ports de jogos para o Arch R com as regras reais dele.