InkSpector 1.02 Copyright 2017 by Mark Incley http://www.inkland.org.uk/ User's Manual Contents ======== 1.0 Introduction 2.0 Requirements 3.0 The Control Panel 4.0 Getting Up And Running 5.0 Acknowledgements 6.0 Version History 7.0 Disclaimer 1.0 Introduction ================ InkSpector is a scriptable Sinclair ZX Spectrum Emulator screensaver for Windows. It emulates and displays virtual Spectrums in a 3D world. Each virtual Spectrum appears as a TV with its display appearing on the screen. Scripts create and control these TVs in the 3D world. Features available: * Spectrum 48K emulation * Spectrum 128k emulation * Scripting, using Lua 5.1 (http://www.lua.org) so you can make the Spectrums dance how you want. InkSpector is supplied with several scripts. See Scripts.txt for details. * .sna, .z80 (all versions) and .szx snapshot file support * .scr (screen dump) file loading support * .rzx replay file support * .rom Interface 2 ROM support * .zip file support - scripts and their required snapshots may be bundled up in a single zip file. * Screensaver control panel preview * Screensaver control panel configuration * Playlists to control which scripts are played. * SmartPlay ensures that all snapshots in your archive file are randomly selected without repetition, even if InkSpector is interrupted. (Anticipated) FAQs ------------------- How do I create my own Check out the Scripts.txt scripts? document supplied with InkSpector What is Lua? Where can I http://www.lua.org learn about it? What language is InkSpector InkSpector is written in C++, written in? assembler and Lua. 2.0 Requirements ================ InkSpector runs on any version of Windows capable of running DirectX 8.1 applications (at the time of writing, that's Windows 98/98SE/ME/2000/XP/Vista/7/8.x/10) including 64-bit versions. A processor running at 700mhz or faster is recommended, although I've had InkSpector chugging away nicely on a P2-300 with a TNT2 video card. 3.0 The Control Panel ===================== InkSpector's settings and the script playlist are accessed using its control panel. This is accessed from Window's Screen Saver selection window (Control Panel->Display->Screen Saver or right-clicking on the desktop and selecting properties->Screen Saver). Press the "Settings" button when InkSpector is selected as the screen saver. You can control which scripts are played from the InkSpector control panel. You can select to play all scripts or just a selection, and whether to play them sequentially or whether they're shuffled first to play them in a random order. In addition, if you have a folder on your hard drive that contains Spectrum snapshots, you can point InkSpector at it so that scripts may access them. The "Archive" script supplied with InkSpector is such a script that uses this folder if it's been set up on the control panel. If you want InkSpector to play from a folder of RZX or other snapshot files, that's the script you want! SmartPlay is an optional feature that ensures that all files within the archive folder (see above) are selected randomly without repetition until all of them have been played. Even if InkSpector is interrupted, SmartPlay will continue where it left off until all files in your archive have been played. SmartPlay doesn't mind if you add, remove or rename files from your archive, it will just quietly update its own internal playlist the next time InkSpector runs. If there are any subfolders within your archive folder that you would like InkSpector to ignore, you can do this by creating a file or folder named ".InkSpectorExcludeMe" within it. InkSpector is supplied with a small archive of snapshots so that it works out-of-the-box. If you do not want InkSpector to use these files when using your own, you can uncheck the "Include InkSpector's own snapshots" box. Note that if you uncheck this box and you do not specify your own archive folder (or it points to a non-existent location) this option will be ignored and InkSpector will use its own snapshot archive. If InkSpector is displaying a game that you'd like to take control of, you can select a key that allows you to play the game, but doesn't cause the screensaver to quit (as normally happens when a key is pressed). Pressing the assigned key pauses the current script, so that you can play the game (or watch the replay, if a replay files is in progress) for as long as you wish. 4.0 Getting Up And Running ========================== InkSpector is supplied with some scripts and snapshot files to get you started, so you can just install and go. I prefer to use InkSpector by pointing its archive folder (by using its control panel - see above) to one full of RZX replay files, such as those available from http://www.rzxarchive.co.uk If you only want to watch InkSpector play these files, create a custom playlist which includes only the "Archive" script. The "Carousel" script will select snapshots from your archive folder if you set it up, too. 5.0 Acknowledgements ==================== InkSpector uses the following software: Lua 5.1 - A scripting language http://www.lua.org RAZE - Z80 CPU Emulator by Richard Mitton (No website available at time of writing) InkSpector uses RAZE 1.06i (no clues for the 'i' stands for :-) based on Richard's RAZE 1.06. This is a version I've customised to add RZX support and improve the Z80 emulation accuracy in some areas. The Sinclair ZX Spectrum 16/48k and 128k/+2 ROMs. Amstrad have kindly given their permission for the redistribution of their copyrighted material but retain that copyright. http://www.amstrad.com zlib - A Compression Library http://www.zlib.net Inno Setup - A great Windows installer program by Jordan Russell http://www.jrsoftware.org/ Thanks to Mark Edwards for the TV model and Mark Potente for the InkSpector logo. 6.0 Version History =================== 1.02 - Maintenance Release - 19th March 2017 --------------------------------------------- Backported several more fixes from the development of InkSpector 2: Support uncompressed .rzx files (which are relatively uncommon) e.g. minder.rzx Allow .rzx files to have frame blocks without a preceding snapshot block. This change allows dizzydice.rzx to play to completion. Additional protection against malformed .rzx files Fixed a potential issue where audio might go silent, especially after repeated muting and unmuting. Reduce the amount of memory used for each Spectrum by 1.5KiB The browse for snapshot archive dialog now starts navigation at the currently selected folder. Fix the 'no available scripts' warning box being shown under some unusual scenarios. Initialised the AY's RNG to a known value. This might have caused noises (usually drum sounds) to go missing occasionally. Fixed a possible problem loading snapshots into a 16/48K Spectrum after loading an IF2 ROM cartridge. 1.01 - Maintenance Release - 29th May 2013 ------------------------------------------ The installer, when run on 64-bit Windows, now runs the 64-bit version of the Windows screen saver settings, so that the selection of the screen saver now sticks. Spectrums, when in exclusive mode (full screen), are now displayed with the correct aspect ratio. SmartPlay will now exclude folders containing a file or folder named ".InkSpectorExcludeMe". Added option to disable v-sync. Fixed blank display when run on multi-monitor systems. InkSpector now displays on the primary monitor of such systems. Fixed a hang in script function inks.IsTextActive(id) if there was at least one text message active and the supplied id didn't match any of the active texts. This bug didn't affect the scripts supplied with InkSpector. Fixed a crash when resuming from a power-down (i.e. coming out of sleep state). Fixed a crash when running a script that had at least one active clone after the Direct3D device is lost (e.g. after pressing Windows-L to lock the desktop, and then returning to InkSpector in preview mode) Fixed exclusive mode Speccies going blank after the Direct3D device is lost (e.g. after pressing Windows-L to lock the desktop, and then returning to InkSpector in preview mode) Fixed "Willy Trilly" and "Miner Willy" scripts not finding their snapshots if the "include snapshots included with InkSpector" option is unchecked. Fixed the beeper sounding rough on long BEEPs (e.g. Sabre Wulf start game jingle) Upgraded to Lua 5.1.5 Upgraded to zlib 1.2.8, MiniZip 1.1 Better protection against malformed .szx snapshot files. Better protection against malformed SmartPlay files (which InkSpector uses to keep track of which snapshots have been selected from a user's archive). Backported several minor fixes from the development of InkSpector 2.0. 1.0 - Finally arrived - 9th July 2008 ------------------------------------- Notable changes since 0.93: SmartPlay has been rewritten so that it no longer resets itself if files are added, removed or renamed from the archive. The Spectrum's beeper and the 128k's AY chip are now emulated. The Carousel script has been updated to fade the Spectrums in and out (four Spectrums playing at once was not a nice sound!) Added Fuller box audio emulation. Added .szx snapshot support Added .scr snapshot support. After loading such a snapshot, the Speccy is paused to allow the screen to be shown undisturbed. Added Interface 2 .rom file support. inks.Random() added to the scripting language which behaves like Lua's math.random(), but uses the Mersenne Twister RNG instead of the standard C library's RNG. Added option to exclude InkSpector's own Snapshot folder if a user one is supplied. Numerous optimisations. 0.93 - 14th March, 2008 ----------------------- Notable changes since 0.90: Added SmartPlay. Added Spectrum 128K support (albeit a mute 128K at the moment) Added support for multi-part RZX files. In scripts, CSpeccy has been replaced with CSpeccy48 and CSpeccy128. To avoid unnecessary complications when loading snapshots in scripts, I've added a nifty little feature that automatically causes a CSpeccy128 to page in the original 48K ROM (not to be confused with the 128K version of the 48K ROM, which is slightly different) when a 16/48K snapshot is loaded into it. This should give 100% 48K compatibility - better than the real Spectrum 128K! The 128K ROM is paged back in when loading a 128K snapshot. Added CSpeccy::SetExclusive which renders only that particular Spectrum's display to the screen (without the TV surround). The Archive script now uses this. Added some new CSpeccy functions. See Scripts.txt for details Fixed a fairly obscure Lua garbage collection bug. It didn't actually occur when using the scripts supplied with InkSpector. Fixed an issue with undocumented/bad Z80 opcodes when playing RZX files, which caused Batman (and possibly others) to lose sync before playback had completed. Upgraded from Lua 5.0 to 5.1.3. Made more Vista compliant by writing the InkSpector log file into \Application Data\Inkland instead of using the folder where InkSpector was installed. Memory optimisations including the introduction of a ROM pool. CSpeccys now access a shared ROM pool rather than loading a copy of the ROM individually. Numerous minor performance optimisations. Countless minor fixes and tweaks. 0.90 - 27th November, 2005 -------------------------- Fixed problem when running InkSpector as a non-admin user on Windows 2000 or XP ("no valid scripts found") 0.89 - 26th November, 2005 -------------------------- First public preview 7.0 Disclaimer ============== Users of InkSpector must accept this disclaimer of warranty: InkSpector is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of InkSpector.