---

Desktop Hacker

Foundation RISCWorld

5. Technical stuff.

These section supersedes the text files that used to be available in the 'Documents' directory on older releases of Desktop Hacker.

5.1. Writing code for Desktop Hacker.

The old external code system used by The Hacker is no longer supported.

Instead, you should code a normal Wimp task, and use Desktop Hacker's SWIs and messages to communicate. This has the advantage that you don't need to program in ARM code - you can use C, BASIC, or any other language. Create yourself an application with a Desktop Hacker axe somewhere in the icon;

ideally, the application name should begin '!dH', but this may not always be appropriate.

There are two parts to Desktop Hacker: the actual DesktopHacker module task, which provides all the hacking facilities that the user uses; and the SWIVe code (so named because it works by claiming the SWI hardware vector), which, when the hot-keys are pressed, stops the game and starts a Wimp task. SWIVe sends Wimp messages to Desktop Hacker (and external tasks; it is a broadcast message) when the game is stopped, restarted, or quit.

Desktop Hacker sends a message to SWIVe telling it to continue when the Continue button is clicked, or when Select is clicked on the icon bar icon, or whatever. Desktop Hacker may also send a Wimp Message_Quit (message 0) telling SWIVe to shut the game down entirely. Other external tasks (including the Task Manager) may send messages to SWIVe. SWIVe will appear in the Task Display either as 'Desktop Hacker Game' if the program interrupted did not call Wimp_Initialise, or the real name of the stopped task if it did.

Apart from the memory of the SWIVe task, there are a few other details Desktop Hacker holds. The only directly readable one is the environment variable dHacker$Obey$Dir, which holds what Obey$Dir held when the hot-keys were pressed.

WIMP messages

Message_HackerTask
Message &82740

Purpose

This message is broadcast by SWIVe to inform Desktop Hacker and any external tasks of a hacking session starting/ending. No parameters are passed using the message; external tasks should call the SWI DesktopHacker_ReadState to find out the current state.

SWIVe sends this message when:

1. The hotkeys have been pressed (or dHacker has been activated by a hackpoint) and the task is initialising.
2. SWIVe has been told to continue by Desktop Hacker, or an external task, and the task is ending.
3. SWIVe has been told to quit by Desktop Hacker, an external task, or the Task Manager, and the task is ending.
4. SWIVe has been told to load a game file; this has been done successfully, and a completely new game position is established.

Message_HackerContinue
Message &82741

Purpose

This message is sent by Desktop Hacker, or any other task, to tell the SWIVe code to restart the stopped program. No parameters are passed.

Message_HackerGameFile
Message &82742

Purpose

This message is sent by Desktop Hacker, or any other task, to tell the SWIVe code to load in the game file whose path is specified.

Format

+12 = 0 (this is never a reply)
+16 = &82742 (Message_HackerGameFile)
+20 = unused
+24 = unused
+28 = unused
+32 = unused
+36 = unused
+40 = unused
+44 = null-terminated filename of game file to load

Message_HackerAltered
Message &82743

Purpose

This message is broadcast by Desktop Hacker whenever the memory of the stopped task has been altered, either by the user, or by certain DesktopHacker_MemoryAccess calls. External tasks that display details in a window that depend on the contents of the stopped game's application memory should rescan and redraw where necessary when this message is received. No parameters are passed.

Note that this message is not broadcast when a game file is loaded which changes the application memory contents completely; instead the SWIVe code broadcasts Message_HackerTask.

SWIs

DesktopHacker_ReadState
SWI &82740

Purpose

This SWI allows external tasks to read information about Desktop Hacker which may be needed to perform their function.

On entry

-

On exit

R0 = 0 if Desktop Hacker is idling or running a single-tasking task
R0 = 1 if Desktop Hacker is running a task that's called Wimp_Init
R0 = 2 if Desktop Hacker has interrupted a task
R1 = task handle of hacked task if R0=1 or 2, else preserved

Use

If your task requires the application memory of a hacked game, you should only allow use of the task when R0=2.

Note that the task specified in R1 does not have the same in it when stopped as when it is running. See the format of saved game files for details of what is in the application area when stopped.

If you just want to access the main application area, though, and not the full info bundles, you should use the SWI DesktopHacker_MemoryAccess.

If you do access Desktop Hacker or its game's WimpSlot directly using Wimp_TransferBlock, be aware that there is a bug in RISC OS 3.7's implementation of the SWI affecting use of the call twice or more in a row between code synchronisations. To combat this, you should call OS_SynchroniseCodeAreas once after each call to Wimp_TransferBlock. Failure to do so on a machine equipped with RISC OS 3.7 but not equipped with the patches produced by Acorn or DoggySoft will result in things going wrong in inexplicable ways - you have been warned.

DesktopHacker_MemoryAccess
SWI &82741

Purpose

This SWI loads and stores data to and from the game's WimpSlot. You should always use this SWI to access the game's application memory, rather than using Wimp_TransferBlock, as (a) this SWI automatically re-maps the word at &8000, and (b) it uses a cache in RMA to make access much quicker (Wimp_TransferBlock is very, very slow). At present, the cache is 8K long. If you do alter the game using Wimp_TransferBlock, you must call DesktopHacker_MemoryAccess 4 to invalidate the cache, or other users of the cache may not like it.

Note, if you're searching through memory, you will find it is much quicker to search forwards rather than backwards, due to the rather simplistic cache algorithm. Only read-cacheing is performed, not write-buffering.

No DesktopHacker_MemoryAccess operation may be used when the game is not being hacked (R0 on exit from DesktopHacker_ReadState is not 2).

On entry

R0 = reason code
other registers dependent on reason code

On exit

dependent on reason code

DesktopHacker_MemoryAccess 0

Purpose

Load one word

On entry

R0 = 0 (reason code)
R1 = address

On exit

R0=value
R1 preserved

DesktopHacker_MemoryAccess 1

Purpose

Store one word

On entry

R0 = 1 (reason code)
R1 = address
R2 = value

On exit

R0 corrupted
R1, R2 preserved

DesktopHacker_MemoryAccess 2

Purpose

Load block

On entry

R0 = 2 (reason code)
R1 = start address (game)
R2 = length
R3 = buffer (in your memory)

On exit

R0-R3 preserved

DesktopHacker_MemoryAccess 3

Purpose

Store block

On entry

R0 = 3 (reason code)
R1 = start address (game)
R2 = length
R3 = buffer (in your memory)
R4 = your task handle, or -1 if in unpaged memory such as RMA

On exit

R0-R4 preserved

Use

Note that the buffer must be paged in when the SWI is used, despite the fact that you pass the task handle. The task handle is needed by Wimp_TransferBlock for efficient transfer.

DesktopHacker_MemoryAccess 4

Purpose

Invalidate cache

On entry

R0 = 4 (reason code)

On exit

R0 preserved

Use

Under Desktop Hacker 1.05 or later, invalidating the cache also ensures that its contents are zeroed. This is to make sure that programs like dHMusic don't find portions of the game's memory in the RMA and generate false alarms.

DesktopHacker_MemoryAccess 5

Purpose

Find length of game

On entry

R0 = 5 (reason code)

On exit

R0 = length of game's real WimpSlot in bytes

Errors

MemoryAccess cannot be used as no game is hacking (&82760)
Bad DesktopHacker_MemoryAccess address (&8275F)
Unknown DesktopHacker_MemoryAccess reason code (&82750)
Plus any errors returned by Wimp_TransferBlock

DesktopHacker_ReadList
SWI &82742

On entry

R0 = list number

On exit

R0 = Desktop Hacker's task handle
R1 = pointer to list block
R2 = length of list block

Use

On exit R1 points to a list (see format of list files), the only difference being that the first four bytes are an offset to the first byte after the end of the list, rather than the header "List".

Note that the pointer is in Desktop Hacker's application space. If you want to read the contents of the list you will need to use Wimp_TransferBlock with the R0 and R1 supplied by this SWI, and the length of block to transfer as R2.

There is no SWI provided to alter lists - doing so would be very slow as very many calls to Wimp_TransferBlock would be needed, along, perhaps, with resizing of the WimpSlot which is not possible as Desktop Hacker is not paged in. If you do want to send a list to Desktop Hacker, simply use the data transfer protocol - make up a Wimp message block as if a list file was dragged to Desktop Hacker (use the icon bar (-2) as the destination window handle; the destination icon handle is unimportant), using Message_DataSave. Data transfer will be conducted as normal, and the window containing the list will be opened. Note that Desktop Hacker does not support RAMTransfer.

Errors

Invalid list number (&8275E)
Any errors returned by Wimp_TransferBlock

DesktopHacker_BreakPoint
SWI &82743

On entry

-

On exit

Registers preserved

Use

This SWI sets a flag which tells Desktop Hacker to interrupt as soon as possible. Usually, this will be immediately, but it may be called later if IRQs or FIQs are disabled, or the processor is in IRQ or FIQ mode. Of course it will also only interrupt if you are the current hacking task.

In order to get all the registers for the Game Info window, not just R0-R8, this SWI is trapped in the SWIVe code; the actual SWI command code does nothing. You will not receive an error if the situation isn't suitable for a breakpoint. Instead, just the SWI command code is called, and so nothing will happen.

This SWI is only implemented on Desktop Hacker 1.06 and above.

* commands

*DesktopHacker command

Purpose

Start a new task or game file to be hacked

Use

This command is used by Desktop Hacker when a game is dragged to it. It cannot be used from the command line. However, there is no reason why external tasks should not use it, if they need to. It should only be used by being passed to Wimp_StartTask, and to be sure of compatibility with special fields, you should surround the parameter of a Run command (if that's what you're using) with quotes. For example, for BASIC:

SYS "Wimp_StartTask","DesktopHacker Run ""CFS#adfs::HD.$.File"""

*Desktop_Hacker

Purpose

This is just the command used to start the Desktop Hacker Wimp task, as is needed by module tasks. Don't use it.

*SetHackPoint *ClearHackPoint *ListHackPoints

5.2 Format of game files and list files.

New GamePos files are typed &3F7. Old files are typed &0D0 and will not be accepted by newer versions of Desktop Hacker. However, their contents are compatible, so old GamePos files may be converted simply by re-typing them.

GamePos files are (optionally compressed) copies of what's inside a stopped game's application memory whilst being hacked, with the following small header. The contents of a stopped game's application memory follow.

There then follows (at 12 or 16) the data. When decompressed, it is exactly the same as what is stored from &8000 in a stopped game. There is a BASIC routine to decompress a game file with compression method 'Sqsh' in !GameInfo.!RunImage, look for 'Squash_Decompress' to find it.

Squashed game files are only supported by Desktop Hacker version 1.06 and later, and dHInfo version 1.04 and later.

Files with version ID 'D101' are only understood by Desktop Hacker 1.07 and later. They are only produced when the 'Don't keep screen memory' option has been switched on.

From &8000 upwards, the data is stored in bundles of:

The order of bundles is important. A null data length (ie. offset of 4) may be used. An offset of 0 terminates the list of bundles, and is the last word in the file.

Order of bundles defined so far under IDs 'D100' and 'D101':

1. The game code itself. Since this starts in memory at &8004 (thanks to the bundle header), the word at &8000 is at the very end of the block, and all the memory from &8004 comes first in the block. This avoids major memory shunting. If data length 0, zero WimpSlot is used. This bundle must exist, even if with a data length of 0.
2. Registers bundle. R0 to PC, all USR mode. This bundle must exist, and have a data length of 64 (16 words). A bundle terminator may occur at any bundle after this.
3. FP registers bundle. Unlike the normal registers, this bundle may have a data length of 0, and indeed will if the machine the game was stopped on had no FP hardware and no FPEmulator loaded. If this bundle does have a non-null data area, it must be 64 bytes long. F0-F7 are stored in double precision (D) format. Some accuracy is lost in the 64-bit D format. This is likely to be insignificant. (E and EP formats cannot be used due to inter-FP system incompatibility.)
4. Mode definition bundle. A data length of 0 means screen unimportant. A data length of 4 means it's a standard RISC OS 2/3.0/3.1 mode number. A data length of more than 4 can only be handled by RISC OS 3.5, and is a mode selector block. Position files saved out from RISC OS 3.5 with a mode selector rather than a mode number cannot be read under RISC OS 2 to 3.1. Desktop Hacker in itself fully supports the new mode and sprite formats. Note, if the mode is in old format, it may well be a shadow variant, so clear the seventh bit before using it where shadow modes are inappropriate, eg. sprites.

5. Screen memory contents bundle. Screen memory must be a fixed number of pages. Transfer from a machine with a small page size to one with a bigger page size may cause problems (the screen appearing too far up, and flickering, generally) if the page boundaries where the screen starts don't coincide.

   Under files of ID "D101" or greater, a data length of 4 has a special meaning (as 4 bytes screen memory seems a tad unlikely!): the one word in such a bundle if the length of screen memory. The actual contents of screen memory in this case are not stored, to save memory on machines that are short on RAM.

6. Miscellaneous info bundle.

   Position	Length	Contents
   +0	4	Mouse shape number and linkage flag (as from OS_Byte 106)
   +4	4	Mouse X co-ordinate
   +8	4	Mouse Y co-ordinate
   +12	4	Flags bits 0-29 as from OS_Byte 200 (Escape/Break state) bit 30 set if mouse bbox is full-screen, else infinite bit 31 as from OS_Byte 229
   +16	4	Keyboard disable state (as from OS_Byte 201)
   +20	4	Escape key number (as from OS_Byte 220)
   +24	4	MonotonicTime when game was interrupted
   +28	4	Key initial delay (OS_Byte 11) when game interrupted
   +32	4	Key repeat delay (OS_Byte 12) when game interrupted

   Further data may be added to this bundle in future. Under Desktop Hacker 1.00, bit 30 of flags (+12) will always be unset. It is impractical to read mouse bboxes directly, more accurately than full- screen/infinite as there is no SWI to do this. However, Future versions of Desktop Hacker may trap the OS_Word calls that set the mouse bbox, and save the bbox, which would allow this. In this case, bit 30 will again become reserved, a new bundle will be added, and the version ID will be increased to D102.

7. Screen info bundle. (If only screen context save areas were more flexible, I could just use them, but no...)

   Position	Length	Contents
   +0	4	Text foreground colour (*)
   +4	4	Text background colour (*)
   +8	4	Text foreground tint
   +12	4	Text background tint
   +16	4	Graphics foreground colour
   +20	4	Graphics backgound colour
   +24	4	Graphics foreground tint
   +28	4	Graphics background tint
   +32	4	Graphics foreground action
   +36	4	Graphics background action
   +40	4	Text window left
   +44	4	Text window bottom
   +48	4	Text window right
   +52	4	Text window top
   +56	4	Graphics origin X
   +60	4	Graphics origin Y
   +64	4	Graphics cursor X
   +68	4	Graphics cursor Y
   +72	4	Text cursor X
   +76	4	Text cursor Y
   +80	4	VDU status register
   +84	4	ScreenStart offset
   +88	4	DisplayStart offset
   +92	4	Screen bank (**)
   +96	4	Display bank (**)
   +100	4	Border colour word (ReadPalette)
   +104	4	Mouse colour 1 word (ReadPalette)
   +108	4	Mouse colour 2 word (ReadPalette)
   +112	4	Mouse colour 3 word (ReadPalette)

   Further data may be added to this bundle in future.

   (*) These values are not accurate in any mode with >16 colours, so you'll notice changing text colours in Desktop Hacker sometimes. This is not my fault - OS_ReadVduVariables simply doesn't return the correct values sometimes!

   (**) The default screen bank (0) in this position is not allowed - you will have to work out the real screen bank number from the shadowness of the mode, if the game has specified a default bank.

8. Palette bundle, only in <16bpp modes. Data length always zero in 16/32 bpp modes. Data length is 256 double words in all 8bpp modes. List of double words (flash1, flash2) in OS_ReadPalette format, starting from the maximum colour, and going down to colour 0; ie. in reverse order. Don't ask why; it's just like that, and not worth changing now.
9. Vector bundle. The data area contains a block of vectors as returned by OS_DelinkApplication.
10. Device vector bundle. This data area contains 12-byte blocks as for the vector bundle, but for device vectors (interrupts). Types 8 and 13 (used by expansion cards) need extra registers, and are ignored - Desktop Hacker shouldn't touch expansion cards anyway.
11. CallEvery ticker events bundle. Each ticker event has three words. The first is the interval, the second the address, the third the workspace.
12. CallAfter ticker events bundle. Each ticker event has three words. The first is the monotonic time (as seen by the application) at which to interrupt, the second the address, the third the workspace.
13. Module chain bundle. Each word is a pointer to a module in application space. This is to prevent games' modules in application space being called when the game is not paged in. However, the only way Desktop Hacker can delink these modules is by killing them and re-initialising them when returning (with OS_Module 10). This is not at all satisfactory (music modules may, for example, go silent), but it's all that can be done. Modules inserted in RMA are disabled by having their service and SWI decode entry points poked to 0.

Further bundles may be added in future. The Version ID will only be increased when the internal format of existing bundles changes, as old versions will refuse to load newer IDs. Bundles marked 'further data...' may be extended without increasing the version ID, so be prepared for them being longer than documented here - always use the bundle length header word to get the length.

5.3. Format of list files

Info text can be used to specify the type of search that produced the list, or the list creator program.

The file type for address lists is &B6E and is titled 'AddrList'. Lists produced by versions of Desktop Hacker earlier than 1.06 have the file type &0D1, and will not be recognised by newer versions. The file contents, however, are compatible, so you can convert an old list to a new list simply by re-typing it.

5.4. Internationalisation.

Desktop Hacker may be altered to work in another language. If more than one language is available, the language may be picked from the Choices window. Currently available languages are English (UK) and German (D). To make a new language, shift-double-click on !dHacker and copy the 'UK' directory with the name of the new language.

The language directory contains a Messages file and a Templates file. The Messages file is self-explanatory, but in the Templates file Desktop Hacker uses its own system of 3D borders, which you will not be able to see in a template editor. However, they have a similar numbering system to the WimpExt and Interface modules, so if you have an editor that supports either of these modules you'll be able to see them if you alter all '�bnumber' validation commands to 'wnumber' for WimpExt, or 'bnumber' for Interface.

The borders are not quite the same, especially as their look can be configured; 0-6 are the same as WimpExt (6 being a new-style group title), and 7 is a version of 0 that can also be slabbed in by pressing Menu (for menu arrows). Remember to change the validation commands back to '�bnumber' once you have finished!

Desktop Hacker supports some other validation commands, again prefixed with '�'. You shouldn't need to tamper with these when translating templates to other languages, but for the record they are:

�r[-]offset

When Return is pressed with the caret in this icon, the icon offset away from the icon number is 'pressed'. The offset system is used rather than absolute icon number so that icon groups can easily be copied, moved, and renumbered.

�e[-]offset

Same as �r, but for the Escape key, to allow persistent dialogue boxes to be closed by pressing Escape, as the Style Guide rightly says, but everyone ignores. Pressing Escape should 'click' the Cancel icon.

�u[-]offset

When the up-arrow key, or Shift-Tab is pressed with the caret in this icon, the caret moves to icon number current icon-offset. (Yes, it's -ve. So if you specify a -ve number, the real offset used will be +ve. This is done because normally pressing up arrow moves to lesser-numbered icons.)

�d[-]offset

When the down-arrow key, or Tab is pressed with the caret in this icon, the caret moves to icon number current icon+offset.

Note that �r, �e, �u, and �d do the same thing with icons affected: If they're writable, the caret will be moved to the icon, if they are option icons, they are selected (deselecting others in the ESG), and otherwise a Mouse_Click event is generated for the icon (possibly making it pop in too).

Note that the validations �r, �e, �u and �d may be used more than once in the same validation, as long as all except the last one select icons rather than position the caret or click icons. For example, the Compare window sets two options and then clicks Compare when Return is pressed in any of the bottom three fields.

�s

When this button is clicked upon, it slabs by being selected. This is useful to give odd-shaped slabbing sprites, like up and down arrows.

�-

When this button is clicked upon, the number in the icon after it is increased by one.

�+

When this button is clicked upon, the number in the icon before it is decreased by one. (Excuse the perverse naming of these two validations!)

You must keep the red 'help' icons in the right place, but you will find that you have to move them around in order to get at the icons beneath them. The help_icon system works by checking each help icon and seeing whether the pointer lies under it. If it does, the icon's message (translated from the token in the red help_icon) is sent to !Help. This is not hierarchical - it is always the first match that is copied. So if icon areas overlap, it is the lowest numbered icon's message that is used.

The only window sizes that are fixed are:

All other window dimensions and icon positions may be altered, for example to accommodate any larger icons. If you do make any bits of window bigger, remember to move the help icons over them! Oh, and remember when you alter icons that the fonts may eventually be bigger than those you're using so leave lots of space in the icons.

If you drag Desktop Hacker's Sprites file to your template editor, you notice you can't actually see the icons. This is because Desktop Hacker processes the sprite names in the file to allow the icons to change on a mode change. To see the icons properly, make a copy of sprite file, and rename all sprites called '22_name' (for VGA-res) or '24_name' (for TV-res) to 'name>'. Then drag this new file into the template editor.

Leave all icons deselected. On startup, Desktop Hacker sets the default option and radio icons itself. Setting any others may mess it up. Also, leave all writable icons empty save for list selectors, the slowdown selector, and the print_copies selector, which should have the default (1) in them. All writable icons must be indirected.

5.5. History of Desktop Hacker.

Foundation RISCWorld