SA:United: how to play together
==============================

The host runs the story: the game uses their save. They create the server and send friends
the code. Up to four people play: everyone joins with that code, and each keeps their own
money, skills and look.
You can play from different houses and with different internet providers. Hamachi and
Radmin are not needed.


1. INSTALLATION (everyone)
--------------------------
  1) You need GTA San Andreas version 1.0 US, clean or a modded build. If the game is from
     Steam or the Rockstar Games Launcher, roll it back to 1.0 US with GTA SA Downgrader.
     If the version is wrong, the mod says so itself at startup.
  2) Extract the SA-United archive into the game folder, where gta_sa.exe is. coop.asi,
     install.bat and the coop folder should end up next to it.
  3) Run install.bat. On a clean game it installs the plugin loader; in a build that
     already has one it changes nothing.
  4) Start the game. The SA:United window opens in the main menu. Later you can call it
     with F9. Type your nickname.
  5) When the host creates a game, the mod checks the Windows firewall. If the firewall
     would not let friends reach the server, Windows asks whether to allow changes on this
     computer. Click "Yes": the mod allows coop-server.exe for all networks. Without it
     friends see "Server is not responding".
  6) If the antivirus deleted coop.asi or coop-server.exe, add the game folder to its
     exceptions and extract the archive again. The mod embeds into the game and starts the
     server itself, which some antiviruses do not like. There are no viruses in it; the
     source code is open on GitHub.

  The builds of host and friend may differ. The host may play a modded build even if the
  friend has a clean game. Mission texts appear in each player's own game language. If the
  friend still cannot load the host's world, give the friend the same build. The easiest
  way is for the host to zip their game folder and send it.

  Modloader mods work. Everyone sees their own models, textures and effects. A car that a
  mod adds under a new number is visible only to those who have that mod.

  The SA:United window, chat and hints are in Russian and English. The language is
  switched at the top of the F9 window, where it says RU and EN. Everyone picks their own
  language.


2. HOST: CREATE A GAME
----------------------
  1) Press F9 and open the "Create game" tab. Choose a save and press "Create server".
     If you are already in a game, the server is created from the current game.
     The "Damage to partner" checkbox above the button lets you hurt and kill each other:
     with bullets, fists, explosions, fire and the car. Without it you are invulnerable to
     each other. The host's choice applies to the whole game until the server restarts.
     The "Block partners' /tp and /tphere" checkbox turns those commands off for partners.
  2) After a few seconds a code like XXXX-XXXX-XXXX appears in the window. Press "Copy"
     and send the code to friends in Telegram, Discord or wherever is convenient.
  3) The code changes at every server start, so send a fresh one each time.
  4) Save as usual. Guests' progress is kept with you in the coop\server-data folder, and
     if the game is in Program Files, in %LOCALAPPDATA%\SA-COOP\server-data. Do not delete
     it. When you save, the guests' progress is saved too.
  5) To play the story from the very beginning, pick "New game" in the "Save" field with
     the arrow keys (it is the last item in the list). You play the prologue yourself, and
     the friend should join right away: they wait and appear next to you when CJ gets on
     the bicycle. The friend's money, weapons and skills in a new game also start from
     zero. The server keeps the old progress in coop\server-data\profiles\old.


3. FRIEND: JOIN
---------------
  1) Press F9 and open the "Join" tab. Paste the host's code with the "Paste" button (or
     Ctrl+V in the code field) and press "Join". The port does not need changing when you
     join by code.
  2) Joining takes up to 20 seconds. Then the host's world loads.
  3) The first time, your skills will be as the host's at the moment of joining, and your
     look is yours: CJ from your game, or from your last save if you joined from the menu.
     After that you level up yourself, and everything stays yours.
  4) If the host started a new game, the window says "The host is playing the prologue".
     Just wait. When CJ gets on the bicycle you appear next to them, and there will be a
     bicycle for you too. When the host gets off the bicycle, a short load starts for you:
     that is how you move into their world.


4. IF THE FRIEND CANNOT CONNECT
-------------------------------
  Some providers, especially mobile internet, do not let a direct connection through.
  Then the host needs a relay, and the connection works on any internet.

  Method A. The metered.ca relay (free 20 GB a month, enough for hundreds of hours of play)
    1) The host registers at https://www.metered.ca (sign-in by email or Google works) and
       opens the TURN Server section.
    2) Creates an App with any name in latin letters, e.g. sacoop-ivan. The app address
       will look like sacoop-ivan.metered.live, and its name matches the first part of the
       address.
    3) Copies the API Key. It is in the panel, under Developers / API Key, or TURN
       Server > Credentials.
    4) Opens the file coop\server.ini with Notepad (it appears after the first server
       start) and writes on the last line the name of their app and the key:
         turn = metered:sacoop-ivan:YOUR_API_KEY
    5) In the game presses F9, "Disconnect", then "Create server" again and sends the
       friend a new code.
    The friend needs to change nothing. If the direct connection does not go through, the
    game switches to the relay after about four seconds.

  Method B. The playit.gg tunnel (if metered.ca is unavailable)
    1) The host downloads the program from https://playit.gg/download, runs it and signs
       into an account.
    2) Creates a tunnel of type UDP to local port 7788. You get an address like
       something.ply.gg and a port.
    3) Creates the server in the game as usual. The playit program must be running at the
       time.
    4) The friend types the address from playit (without the port) into the "Invite code
       or IP address" field and the port into the "Port" field, then presses "Join".

  Method C. If the host has a "white" (public) IP and UPnP is enabled in the router,
  everything works as is. If UPnP is off, forward port 7788 (UDP) to the host's computer.


5. IN THE GAME
--------------
  F9     the SA:United window
  T      chat (Enter sends a message). While the chat is open your character stands and
         does not jump
  B      voice chat, while the key is held
  G      get into the nearest car as a passenger (next to your partner if possible)
  Triangle on a gamepad, hold for half a second: get in as a passenger
  F2     players: who has how much money, and money transfers
  RMB    as a passenger: lean out of the window with a weapon (fire with LMB)
  /tp    a chat command: asks permission to teleport to your partner. If there are several
         partners, type /tp and a nickname: the chat lists whom you can call
  /tphere a chat command: calls the partner to you (by nickname if there are several)
  /goto  a chat command: /goto x y z teleports you to that place (outdoors only, and the
         game puts you on the ground). Handy when a partner is lost far away. It asks no
         one; if the host has blocked the teleport commands, partners cannot use it either

  On /tp and /tphere the partner answers with Y (yes) or N (no), and the teleport happens
  only after their agreement. You cannot /tp into a building, and you cannot /tphere
  anyone out of a building.

  In the F2 window everyone's money is visible. The $ button in a friend's row sends them
  your money: type an amount and press "Send". The window closes with the same F2 key or
  Esc.

  Story missions are started by the host, and a mission begins when everyone has stepped
  into the marker. If the friend reached the marker first, the host sees an invitation and
  with Y appears next to them at once. The friend sees the same objectives, markers and
  cutscenes, hears the same lines and the host's phone calls when standing nearby, and
  receives the same reward. In cutscenes their character is next to CJ: standing, smoking,
  leaning against a wall or sitting, and does not jump from spot to spot between shots.
  They look at whoever is speaking, nod, shift from foot to foot, glance at a watch and
  chew gum. Enemies attack everyone, and anyone can hurt them. Shops, food, the gym, the
  barber, tattoos and tuning are each player's own, but you can see how your partner eats,
  works out or gets a haircut. Driving, motorcycle, bicycle and plane skills are shared:
  the highest of yours is used. The stats in the pause menu are shared too.

  In-engine mission scenes (with the bars top and bottom), the partner next to the host
  watches with the same camera as the host. In the lowrider contest and the beach dance
  the friend plays next to the host and their score counts into the total. The boxes in
  the Ryder house robbery can be carried and loaded into the van by any of you: a box is
  picked up with the car-entry button.

  When the host plays through a mission, the new story progress (opened areas, safehouses)
  reaches the friend with a short load. It starts when the friend steps into the marker of
  the next mission, or after 10 minutes if there are no missions. After it the friend
  stays in the same place with the same weapons, money and skills, and their car stands
  next to them again.

  Side jobs (taxi, ambulance, fireman, police), races, stadiums, schools, the shooting
  range and freight runs are each played in your own game. The friend can do them while
  the host has no mission running. The money and skills from them stay with the friend.
  But if the activity is needed for the story, e.g. driving school, the host must do it.
  A job or a race can be done together: within the first 20 seconds after it starts press
  Y, and the other player gets an invitation. The one who accepts is moved by the game
  next to the caller. In the burglary van and the freight truck they sit as a passenger,
  while in a taxi, ambulance, fire and police car, in races, on the bicycle, the motorcycle
  and at the pimp job an identical vehicle appears next to them. Both work the job:
  patients get into either of your ambulances, the pimp's girl gets into the car of
  whoever drove up to her first, both put out fires and catch criminals, and everything
  counts into the shared objective. In the house burglary both are let in: the item the
  second player carried out and put down by the van's rear doors (F) counts into the
  shared take. The noise meter is each player's own, and the homeowners wake up from the
  noise of either of you. In a taxi there is always one passenger seat, so each drives
  their own fares: for the second player their taxi job starts by itself, and both receive
  the money for all passengers. Their own passengers appear once they have driven away
  from the first one. A job or trial finished by one counts for both, together with the
  reward. In a shared job the second player's money arrives as they go, per passenger or
  delivery. In the shared courier job the second player throws their own packages the same
  way: Q or E and a shot.

  Stadiums can be done together too (Kickstart, Blood Ring, the 8-Track and Dirt Track
  races), the quarry job, the valet shift at the hotel and the shooting range. On the
  stadium the second player ends up on the arena next to the caller, on their own
  motorcycle or an identical car. The coronas and checkpoints they collect count into the
  shared total. In the quarry the second player gets an identical bulldozer or dump truck
  when the caller gets into theirs, and the rocks and bombs they push count too. In the
  valet shift anyone can move the guest's car. The shooting range is joined by stepping
  into its marker: the second player steps into the same booth with the same weapon, and
  their hits on the targets right in front of the booth count into the shared total.

  Smoke's courier job in the countryside (Cesar calls about it on Mondays and Fridays by
  day, on Wednesdays and Saturdays at night) exists only in the host's game. The friend
  nearby sees his van, markers and money bags. They can also ram the courier's van or
  shoot at it and pick up the dropped bags and the package. The money for every bag and
  the package is received by everyone within 300 m of the host.

  Many activities can be turned into a contest: the basketball points trial, pool,
  blackjack, roulette and the wheel of fortune at the casino (slot machines and video
  poker do not count), club dancing, the lowrider meet contest, Kickstart, Blood Ring,
  8-Track and Dirt Track at the stadiums, the races and the "Beat the Cock!" triathlon.
  Within the first 20 seconds press U, and the other player gets a challenge: Y accepts
  it, N declines. The one who accepts plays the same thing in their own game and must
  start within 3 minutes. For dancing and basketball the acceptor is moved to the
  challenger at once: on the dance floor the dance starts by itself and both dance side
  by side. During a contest a scoreboard with both scores is visible at the top of the
  screen. While your own game has not started, it also shows how much of the 3 minutes is
  left and how to start it. At the end the scoreboard shows the result in large letters,
  and the winner also appears in chat. In basketball, dancing, at the lowrider meet and in
  Kickstart the points are compared, at the tables the winnings, in races, the triathlon
  and Blood Ring the time. If you do not press U, you play as usual, alone. In a race and
  the triathlon the same window still has a Y, to do them together.

  The race on the city circuit is played together in the shared world. While you are
  driving your own car or bike, the first 20 seconds of the drive allow U: it challenges
  everyone to a race. Y accepts it, N declines, and whoever accepted while driving is
  taken to the start line. All racers stand on the grid in two rows, the cars are held
  still for the 3-2-1 count-down, and on GO the race runs: two laps of one circuit
  through the city, 18 checkpoints, with the marker and the radar blip of the next one
  on screen. It is a clean race: the guns are put away, only ramming counts. The first
  over the line ends the race for everyone, and the box at the top of the screen shows
  how far each racer has gone. If you leave the route, a hint offers Y to return to the
  track (you come back just past your last checkpoint) or N to keep driving, and a wreck
  is brought back to the route by itself. A death or an arrest takes the race off for
  everyone.

  Pool can be played together at one table. Walk up to the table and press U while the
  stake choice is on screen. Do not place the stake until your friend answers. When your
  friend presses Y, they become the second player at the table and you take turns. Each
  strikes with their own mouse or gamepad while watching through the table camera. Both
  stand at the table with cues and see the other aim and strike. The winner of the frame
  appears in chat.
  If the stake has already been placed, your friend plays their frame at another table,
  as a contest.

  A passenger can shoot from the window. Hold the right mouse button to lean out with a
  weapon and fire with the left. The firearm you got in with stays in your hands. If you
  got in without one, you hold an Uzi, Tec-9 or MP5 if there is one. The driver is given
  an SMG as usual. Any firearm can be shot from the window: pistols, shotguns, SMGs,
  assault rifles and rifles. While you are leaning out, the mouse wheel (the d-pad up and
  down on a gamepad) changes to a weapon that has ammo, and the radio is not switched by
  the wheel at that moment. If you got in next to your partner as a passenger, your
  followers (the mission people, e.g. Denise, and your gang) sit down in the free seats
  after a couple of seconds, and get out when you get out. The board on the roof and the
  convertible's roof are the same car for all players.

  The waypoint you set on the map in the pause menu is seen by your partner on their radar
  and map. When you are in a car, on a motorcycle or a bicycle, driving or as a passenger,
  the radar shows the route by roads: a red line to your own waypoint, or, if you have no
  waypoint, to your partner's, a yellow line to the mission objective. The route can be
  turned off in coop\coop.ini, section [game]: gps = 0.
  A house bought by one of you appears for everyone. Above your partner's head their
  health, armour, weapon and wanted stars are visible. The partner on the radar and map
  is shown as an arrow turned the way they are walking or driving. Each picks the colour
  of their own arrow in the F9 window or with the /blip chat command (white, red, green,
  yellow, your own colour as RRGGBB, default): that is the colour in which your partner
  sees you. Your partner's blip on the radar and the label above their head can be
  removed in the file coop\coop.ini, section [game]: the lines partner_blip = 0 and
  name_tags = 0. To bring back a dot instead of the arrow: partner_arrow = 0.

  Weapons, health packs and money on the ground are shared: what one of you took is gone
  for the rest. Horseshoes, oysters, photos and graffiti count for everyone. Mission
  objects, fire, gang territories, plane landing gear, hydraulics and trailers are seen
  by all. Explosions, rockets, grenades, tank shots, fire truck water, trains and
  remote-controlled models are also seen by everyone. Any of you can get into a train
  that no player is driving and drive it yourself. While the host is on a story mission
  other people's trains are closed. A gang territory war near the host is run by the
  host, but provoking it by killing gang members can be done together. A friend further
  than 100 m from the host can start their own war, and the host will see it in chat.
  Everyone sees people inside buildings, Pay 'n' Spray and garage doors, the police
  helicopter spotlight, the car on the tow truck's hook and NPCs shooting from cars, and
  the horn is heard by all. The second player sees the parachute canopy as well. A fire
  your partner put out goes out for the host too. The weapon a mission gives CJ is
  given to the friend as well, so they can help with the spray can too. In the desert
  missions Black Project and Green Goo the jetpack goes round the team: the moment one
  of you takes off, the others get their own pack at once.

  Cheat codes for weather, traffic, pedestrians and game speed affect everyone. Cheat
  codes for weapons, money, health and cars affect only the player who typed them.

  A cutscene is skipped together. One presses Enter, the others get a question and each
  agrees with the same Enter or declines with the Esc key. The scene is skipped when
  everyone has agreed.


6. IF SOMETHING IS WRONG
------------------------
  * No invite code. The host has no internet, or the firewall blocks the server. Try
    method A or B from section 4.
  * The friend sees "Server is not responding", even over a local network. Most often
    the host's firewall or antivirus is in the way. The host creates the game again and
    presses "Yes" in the Windows window (step 5 of installation). If there is no window
    and the friend still cannot get in, check that the antivirus has not deleted or
    blocked coop\coop-server.exe.
  * The SA:United window does not appear, and F9 does not work. Most likely install.bat
    was not run, or the files are not next to gta_sa.exe.
  * The game closes at once with the error "ASI Loader: This library isn't supported".
    This happens when the game already had Widescreen Fix or another mod with its own
    vorbisFile.dll loader, and install.bat version 0.3.1 or older renamed that loader to
    vorbisHooked.dll. Run the install.bat from this version: it puts the loader back.
    By hand: delete vorbisFile.dll and rename vorbisHooked.dll to vorbisFile.dll.
  * Wanted stars do not disappear. One star fades by itself if there is no police
    nearby. Two or more do not burn out on their own even in the normal game: you need
    Pay 'n' Spray, a bribe or a save.
  * The host's world does not load for the friend. You have different versions of the
    game or of the mods. If the chat writes about main.scm, your story file
    data\script\main.scm differs. Take the game folder from the host.
  * Your friend cannot be heard. You have to speak while holding B. While it is held,
    "Microphone" lights up on the left of the screen, and your friend sees there that you
    are speaking. If the microphone did not open or it sends silence, the game will write
    about it in chat. Then in Windows open Settings > Privacy > Microphone, allow access
    for desktop apps and check that the right microphone is the default recording device.
  * The game crashed. Write about it at github.com/demondante050-collab/SA-United/issues
    and attach the files coop.log and crash.log from the coop folder of the game that
    crashed. If you started the game again after the crash, attach coop.old.log too: it
    holds the log of the previous run.
