xyWords README.TXT
==================

Version 1.0.3 - 1st May, 2023

THIS GAME IS DISTRIBUTED AS FREEWARE - DO NOT PAY FOR THIS GAME
NO SUPPORT/WARRANTY IS GIVEN - USE AT YOUR OWN RISK
DO NOT EMAIL ME ASKING FOR HELP OR SUPPORT

License
-------
xyWords and all of its utilities are distributed as freeware.
Freeware means you do not need to pay for the license to use xyWords.
Please see "Credits" section at the end of this document for 
important references regarding game assets.

Change Log
----------

v1.0.3 - 1st May, 2023
xyPE\FIX: Changed config loader to work properly with EGA/VGA

v1.0.2 - 15th April, 2023
xyWords\ADD: Additional trace steps for timer debug
xyWords\FIX: Change the way timer detail is being stored

v1.0.1 - 15th April, 2023 
xyWords\ADD: /T command line switch to enable debug tracing file TRACE.TXT
xyWords\FIX: EGA/VGA Palette 3&5 had grey instead of white

v1.0.0 - 10th April, 2023 - Initial Release

What is xyWords?
-------------
xyWords is a cross-worded anagram puzzle where you use letters stored in a 
circle to find words in the puzzle and clear the level. 

It is a loving tribute to "WordScapes" which you can find on modern on 
Apple/Android/Windows devices.

I will host it on my personal website: Https://4am.org/xywords


Why did I make this?
--------------------
As a kid of the 90s I used to use QB and make all sorts of annoying and fun 
projects.
I used to be a Visual Basic 1x-6x developer but hung up the keyboard around 
2008.
Today, I spend a lot of time mucking around with retro computers.
I thought it would be fun and challenging to try to write something in QB 
for my XT luggable.


System Requirements
-------------------
xyWords is designed to run on DOS-based IBM-PC compatibles.

Although it may run on a variety of machines the following is the 
targeted minimum:
	- Intel 8088 at 4.77mhz
	- 384KB RAM
	- CGA graphics
	- 360KB Floppy (Pico) or 3MB Hard Disk (Full)
	- MS-DOS 2.11 or higher

Distribution is planned as follows:
XYWPICO.ZIP - 360K player only with selected assets
XYWFULL.ZIP - Player, Editor and Utilities - >3MB disk required


Graphics Mode Specifics
-----------------------
xyWords has been developed for CGA-based graphics cards.
The target resolution is 320x200x4 colours for xyWords
xyPE and Utilities may use the 640x200x2 mode

There is a 'fall-back' mode for EGA/VGA whereby the CGA color palettes
will be simulated. The same 4-colours will be used as in real CGA.

See the section "Configuration" in this document for more details.

If you're using hercules mono (HGA) you can use HGCIBM or similar to
emulate CGA and simply select CGA mode. This is unsupported but should work.


Gameplay, Rules
---------------
xyWords revolves around word puzzled and their keyword.
This releases comes with 50 bundled puzzles organised into 3 "collections"
and "Free Play" puzzles which are unlocked ready to play.

It is recommended new players try out the "Welcome" collection first.

xyWords offers two ways to play puzzles:
	1. Free Play - Select a custom puzzle, or an unlocked built-in puzzle 
	and start playing.
	This is a casual mode and does not save progress.
	As you complete collections more puzzles will unlock in free play.
	
	2. Collection Play - Play through indivual puzzles to complete a collection. 
	Progress and statistics are automatically saved upon puzzle completion.

Words must conform to TWL06 database (https://www.wordgamedictionary.com/twl06/)

Puzzles consist of a single key word of 4-7 letters in length.
This is the minimum requirement to constitute a puzzle. 

An example Key Word would be: "GRAPH"

This Key Word is shuffled and stored into the circle. Example: "HGAPR"
You can use these letters to form valid words (as per TWL06 database).

An example of a valid word would be: "HARP"  
An example of an invalid word would be: "PARA" as there is only 1xA in 
the circle.

Puzzles are laid out on the board.

The board will always have 1 keyword and may have:
	- Cross-Words that intersect the keyword or other Cross-Words
	- Puzzle Words that do not intersect other words but appear on 
	the board.
	
Cross and Puzzle Words may be the same length as a keyword (an anagram of).
Keyword, Cross-Words and Puzzle Words must be cleared before a
puzzle is complete.

Bag Words do not appear on the board and do not need to be found to 
complete a puzzle.

Words may not "border" another word.
PEP borders SEEPS and creates an invalid word "SEEPSE"
Invalid: 		Valid:
     P				P
SEEPSE			  SEEPS
	 P				P

Words must have atleast 1 letter not intersecting with another word:
Valid word ERE can be completed by only completing SEER, TEST and SEE 
This means ERE is failing the rule as you can complete it only 
with intersecting words.

Invalid: 		Valid:
  S 			  TEST 
  E 				E S
 SET			    ERE  
 ERE				R T
 E S
   T


Collections
-----------
As mentioned above, 3 collections are included:

1 - Welcome (Easy/Normal) - 9 puzzles
Designed to show off the features of the game.
You start off with basic puzzles and then get introduced into the 
puzzle concepts.

2 - Chill (Normal/Hard) - 12 puzzles
Fun, Casual puzzles that get trickier as you progress.

3 - Spicy (Hard) - 9 puzzles
Challenging puzzles with no hints, no help and tough limits.


User Interface - Puzzles
------------------------

While playing a puzzle you will have a few portions of the 
screen to refer to:

1. Board - area where Key Word, cross-words and puzzle words 
are stored.
2. Circle - area where shuffled letters of the KeyWord is stored.
3. Status - area that shows puzzle progress (timer and penalty 
depending on mode)
4. Rack - area where words are typed ready to submit 

Controls
--------

xyWords is operated with the keyboard.
During menus you will see the on-screen info for progressing.
While playing a puzzle you can use the following:

[A-Z] to type a valid letter (note, if the letter is not part of the 
puzzle it wll not show)

[BACKSPACE] to delete letter(s) in the rack
[ENTER] or [SPACE] to submit the word in the rack
[F1] for quick reference help 
[F2] to mute the PC Speaker sounds
[ESC] to bring up the game menu
[LEFT] - View words collected in the bag
[UP] - Re-Shuffle the circle


Making your own Puzzles and Collections
---------------------------------------

xyPE (xyWords Puzzle Editor) is included in the full distribution.
It provides a keyboard-driven user interface allowing you to make puzzles, 
collections and additional game assets (like table patterns, backgrounds)

Refer to xyPE.txt for detail on the editor.
Refer to technote.txt for detail on how to create game assets "by hand". 


Limits
------
-Puzzles can use up to 19(x) and 11(y) board space.
If you put a word on the board that extends past 19x and 11y it will 
cause unexpected results or crash.

-There are no validations in place for custom puzzles.

-Error handling is non-existant - missing files will crash.

-Progress management is primative.

Future Plans
------------
These are all subject to me having time/motivation to continue.

- MDA or Text mode version, for PCs with less than 256KB RAM.
- VGA port of the CGA version.
- A better version of Puzzle Editor with Validation/rules.
- Puzzle Validation.
- Granular/Enhanced progress management.
- Powerups/Unlocks - to assist with finishing puzzles.


Credits
-------
xyWords was heavily inspired by the mobile game - WordScapes.
WordScapes is a free-to-play game (not a pay to win).
WordScapes is owned by PeopleFun and you can check out the game on your
favourite mobile app store.

Inspiration to target CGA - https://www.youtube.com/PCRetroTech

Code related:
Idea for CGA 6-Palette code - https://www.youtube.com/watch?v=tI7LqShM9WQ&t=142s

Routine for viewing text files:
TEXTVIEW.BAS - https://thedubber.altervista.org/qbsrc.htm 

Routine for reading directory contents using assembly:
GETDIR$ - Alt255 on https://www.tek-tips.com/viewthread.cfm?qid=198826

Routine for reading BMP files:
BMP2CGA - http://petesqbsite.com/sections/tutorials/tuts/loading_bmps.html

Table Patterns are from talented artist Poloviiinkin
These are stored in the \patdata folder
These are licenced under Attribution-ShareAlike 4.0 International
Details here: https://creativecommons.org/licenses/by-sa/4.0/deed.en
The itch page is here: https://poloviiinkin.itch.io/
I have used the pack of tiles and patterns from this pack: 
	https://poloviiinkin.itch.io/1-bit-patterns-and-tiles
If you find these patterns and tiles interesting - please consider giving
them a donation.

I heavily relied on the awesome dithertron
https://8bitworkshop.com/dithertron/
This lets you put in a full colour picture and it will smartly adapt
and dither the picture to suit your target system and palette.

Table Image Backgrounds are stored in \picdata folder
m* - These are my own photos, you are free to use them under public domain.

z* - Collected from various websites
z1_5  - https://www.autosport.com/f1/news/the-f1-moments-that-defined-the-1980s-4982738/4982738/
z2_5  - Https://commons.wikimedia.org/wiki/Category:IBM_Model_F_Keyboard#/media/File:IBM_Model_F_AT.png - Raymangold22
z3_6  - https://personal.garrettfuller.org/blog/wp-content/uploads/2018/10/macintosh.jpg
z4_6  - https://www.raspberrypi.com/app/uploads/2021/08/PC5150_color-1536x1099.jpg 
z5_5  - https://en.wikipedia.org/wiki/Atari_2600#/media/File:Atari-2600-Wood-4Sw-Set.png - Evan-Amos
z6_2  - https://commons.wikimedia.org/wiki/File:ZXSpectrum48k.jpg - Bill Bertram
z7_2  - https://commons.wikimedia.org/wiki/File:Commodore-64-Computer-FL.jpg - Evan-Amos
z8_2  - https://commons.wikimedia.org/wiki/File:Adlib_sound_card_version_1.5.jpg - Bratgoul
z9_4  - https://www.discover1770.com.au/tours/amphibious-larc/
z10_2 - https://www.guidovanhelten.com/projects/brim-victoria

o* - Collected from freesvg.org 

o1_3  - https://freesvg.org/gameboy-tetris
o2_4  - https://freesvg.org/comic-robot
o3_5  - https://freesvg.org/tv-computer-system
o4_5  - https://freesvg.org/old-style-game-controller-vector-clip-art
o5_5  - https://freesvg.org/orange-fish
o6_2  - https://freesvg.org/lego-man
o7_6  - https://freesvg.org/bad-girl-retro-image
o8_5  - https://freesvg.org/grey-disk
o9_5  - https://freesvg.org/notepad-with-pencil
o10_3 - https://freesvg.org/tapeplayer
o11_5 - https://freesvg.org/game-system-in-japan

these files are stored in \assets folder and are used in game
colfin - https://unsplash.com/photos/_XTY6lD8jgM	Giorgio Trovato
lev - https://unsplash.com/photos/dChZrZx6mf8	Daniel Olah
stop - https://unsplash.com/photos/nPPyyii1oIg	Aleksandr Kadykov
timer1 - https://unsplash.com/photos/x8He9JItX2o	AB

these files are stored in \picdata 
u* files are collected from unsplash.com
u16_6 - https://unsplash.com/photos/hBzrr6m6-pc	Jamie Street
u15_1 - https://unsplash.com/photos/2W-QWAC0mzI	nasa
u14_6 - https://unsplash.com/photos/mwWZTLr9Tcg	Ingo Schulz
u13_1 - https://unsplash.com/photos/VYFEByzg7qw	Steve DiMatteo
u12_5 - https://unsplash.com/photos/Fi47SbeEg2k	Steve Sewell
u11_1 - https://unsplash.com/photos/U8OYfPBceWE	MIO ITO
u10_5 - https://unsplash.com/photos/ZOSkWlDVCsE	Yu Kato
u6_6  - https://unsplash.com/photos/up8ooQ1Pm2s	vackground.com
u7_5  - https://unsplash.com/photos/p0j-mE6mGo4	Lorenzo Herrera
u3_4  - https://unsplash.com/photos/qvI3wvjSoHE	Dieter Pelz
u4_4  - https://unsplash.com/photos/YerVHy1nXq8	Christine Ellsay
u2_3  - https://unsplash.com/photos/Y1vNJCM7nyw	David Clode
u1_5  - https://unsplash.com/photos/Sy95bMYqrP0	Do Photography
u5_4  - https://unsplash.com/photos/Es4vkIk90LI	Phillip Flores
u8_1  - https://unsplash.com/photos/4cGR8wgtxR8	BoliviaInteligente

f* files are collected from freepik.com
f1_1 - by catalyststuff https://www.freepik.com/free-vector/book-paper-with-feather-pen-ink-cartoon-icon-illustration-education-object-icon-concept-isolated-flat-cartoon-style_10848243.htm#&position=18&from_view=collections
f2_3 - by catalyststuff https://www.freepik.com/free-vector/vintage-television-cartoon-icon-illustration_10340616.htm#page=2&query=retro%20tv&position=10&from_view=search&track=ais
f3_3 - by catalyststuff https://www.freepik.com/free-vector/toaster-bread-food-technology_10549649.htm#&position=26&from_view=collections
f4_3 - by freepik https:/freepik.com/free-photo/beautiful-planets-space_22896237.htm#&position=13&from_view=collections
f5_4 - by kjpargeter https://www.freepik.com/free-photo/3d-abstract-background-with-extruding-hexagons-design_33921625.htm#&position=1&from_view=collections
f6_1 - by freepik https://www.freepik.com/free-photo/80s-trainer-doing-exercises_34089297.htm#&position=33&from_view=collections
f7_3 - by freepik https://www.freepik.com/free-photo/retro-computer-technology-with-monitor-hardware_34134928.htm#&position=38&from_view=collections
f8_5 - by catalyststuff https://www.freepik.com/free-vector/cute-koi-fish-cartoon-vector-icon-illustration-animal-nature-icon-concept-isolated-premium-vector-flat-cartoon-style_22961535.htm#&position=22&from_view=collections







