Generator rozkładów bdeal

Dokumentacja do programu bdeal dostępna jest w osobnym dokumencie (tylko w wersji anglojęzycznej).

API dla programistów

Dokumentacja znajduje się tutaj.

Uwagi wstępne

W programie obowiązuje angielskojęzyczne nazewnictwo.

Gracze oznaczeni są symbolami (od północnego w kolejności zegarowej):
N (North), E (East), S (South) i W (West).

Oznaczenie kart (od najstarszej):
A (As), K (King - król), Q (Queen - dama), J (Jack - walet), T (Ten - 10), 9, 8, 7, 6, 5, 4, 3, 2.

Symbole kolorów (od najstarszego):
S (Spades - piki), H (Hards - kiery), D (Diamonds - kara), C (Clubs - trefle).
Symbol N oznacza bez atu (No trump).

Wersja z Graficznym Interfejsem Użytkownika (GUI)

Skrypty pobierające rozkłady

Wstęp

Bridge Calculator umie automatycznie pobrać rozdania z turniejów. W tym celu korzysta z dedykowanych poszczególnym turniejom skryptów których zadaniem jest ściągnięcie z Internetu adresów plików (URLi) z których program będzie mógł pobrać rozkłady rozdań. Każdy skrypt jest plikiem z rozszerzeniem .lua.

Gdzie umieścić skrypty?

Program szuka skryptów (plików z rozszerzeniem .lua) w następujących lokalizacjach (dwie ostatnie dotyczą jedynie wersji dla GNU/Linuksa):

• <katalog roboczy>/downloaders/

• <katalog domowy użytkownika>/bcalc/downloaders/

• <katalog domowy użytkownika>/.bcalc/downloaders/

• /var/lib/bcalc/downloaders/

Jak napisać skrypt?

Bridge Calculator obsługuje skrypty napisane w języku Lua.

Lua jest jednym z najbardziej popularnych języków skryptowych. W Internecie dostępne są liczne materiały szkoleniowe i samouczki. Napisano na jego temat wiele książek. Jedną z nich, jest dostępna on-line Programming in Lua - znakomita pozycja autorstwa Roberto Ierusalimschy. Przed przystąpieniem do pracy warto też zapoznać się ze skryptami dystrybuowanymi wraz z Bridge Calculatorem.

Plik ze skryptem powinien być zapisany przy użyciu kodowania UTF-8 albo ASCII i w pierwszej linii powinien zawierać komentarz z nazwą turnieju (najlepiej w formacie: <nazwa miasta w którym odbywają się zawody>, <nazwa turnieju>).

W skryptach dedykowanych do Bridge Calculatora można korzystać ze wszystkich standardowych bibliotek Lua.

Ponadto dostępne są dodatkowe funkcje:
• url.download(adres) - funkcja pobiera z Internetu plik o podanym adresie i zwraca jego zawartość w postaci łańcuch tekstowego (w przypadku błędu zwraca nil), dodatkowo zwraca ostateczny adres pliku (po ewentualnych przekierowaniach);
• url.download_check(adres) - funkcja pobiera z Internetu plik o podanym adresie i zwraca jego zawartość w postaci łańcuch tekstowego (w przypadku błędu przerywa wykonywanie skryptu i wyświetla stosowny komunikat użytkownikowi programu), dodatkowo zwraca ostateczny adres pliku (po ewentualnych przekierowaniach);
• url.escape(str);
• url.unescape(str).

Celem skryptu jest wypełnienie tablicy (array) results. Każda komórka tej tablicy opisuje pojedynczy plik z rozkładami i sama jest tablicą (table) która powinna zawierać pola:
• url - adres strony z rozkładami rozdań (adres pliku: .pbn, .lin, pliku frekansów KoPSa, itd.);
• name - (opcjonalnie) nazwa wyświetlana użytkownikowi (może być to np. data określająca kiedy rozegrano turniej).

Lista rozdań do analizy, kopiowanie z wydruków KoPSa

Lista rozdań do analizy (bezpośrednio po włączeniu programu pusta) znajduje się w lewej części okna. By dodać do niej rozdanie użyj pierwszego od lewej przycisku znajdującego się pod listą. Program zapyta o: nazwę rozdania (ang. name) (jej podanie nie jest konieczne), kolor atutowy (ang. trump suit), wistującego (ang. on lead) lub rozgrywającego (ang. declarer) i rozkład kart (ang. distribution).

Rozkład kart możesz przykleić z pliku z rozkładami wygenerowanymi przez KoPSa.‪‎ W tym celu zaznacz w dokumencie z rozkładami odpowiedni rozkład, skopiuj go (zwykle za pomocą menu Edycja > Kopiuj lub skrótu klawiszowego ctrl+c) i wklej w pole rozkładu dodawanego rozdania (np. za pomocą skrótu klawiszowego ctrl+v).

Możesz też pobrać rozkłady bezpośrednio z Internetu lub pliku z frekansami KoPSa (drugi przycisk od lewej).

Przykłady dopuszczalnych formatów dla wpisywanego rozkładu

Wszystkie poniższe przykłady dotyczą tego samego rozkładu.

Format pełny (dla wpisania renonsu można użyć "-" lub "=="):

         8
         Q96
         AJT32
         AJ92
QJ53              AK962
AKT542            J8
-                 9654
KQ3               T8
         T74
         73
         KQ87
         7654

Format wzorowany na PBN (domyślna kolejność podawania rąk to: N, W, E, S). Spacje rozdzialają kolejne ręce, zaś kropki kolejne kolory (pisanie "-" dla renonsu nie jest więc konieczne):

8.Q96.AJT32.AJ92 QJ53.AKT542..KQ3 AK962.J8.9654.T8 T74.73.KQ87.7654

Format wzorowany na PBN z jawnym wskazaniem, że pierwszą ręką jest S (dalej w kolejności zegarowej, tj. S, W, N, E). Podanie ostatniej ręki jest opcjonalne (we wszystkich formatach) gdy podajemy rozkład pełnego rozdania, tj. gracze mają po 13 kart:

S:T74.73.KQ87.7654 QJ53.AKT542..KQ3 8.Q96.AJT32.AJ92

Wersja konsolowa

Polskie znaki w konsoli pod Windows

Aby polskie znaki były prawidłowo wyświetlane, należy kliknąć prawym przyciskiem myszy na górny pasek okna z konsolą i z menu kontekstowego wybrać: Właściwości -> Czcionka. Następnie wybrać czcionkę Lucida Console.

Obsługa

Zaraz po uruchomieniu program zapyta kolejno o: rozkład kard (karty posiadane przez kolejnych graczy), kolor atutowy i gracza do którego należy pierwszy wist.

Karty gracza należy podać w formacie: {piki}.{kiery}.{kara}.{trefle} (znak . separuje kolejne kolory) albo {piki} {kiery} {kara} {trefle} (używając symbolu - do wskazania renonsu), np. AKQJT2..642.AQT9 albo AKQJT2 - 642 AQT9. Wybór (ten i  wszystkie kolejne) zatwierdzić ENTERem.

Kolor atutowy oraz wistującego wskazujemy wpisując ich symbole (zgodnie z wcześniejszymi uwagami).

Program (po dokonaniu obliczeń, co może chwile potrwać) powinien wyświetlić wpisany wcześniej rozkład kart. Liczby znajdujące się przy kartach wistującego oznaczają ilość lew jaką weźmie on po zadysponowaniu każdej z kart (przy założeniu bezbłędnej gry wszystkich graczy w dalszej części rozdania).

Można teraz wskazać kartę wistu wpisując jej miano i kolor (w dowolnej kolejności). Program przeanalizuje i wyświetli sytuację po zagraniu danej karty (i umożliwi wskazanie dalszych zagrań). Opcjonalnie można wpisać x jako miano, lub w ogóle je pominąć co oznacza najniższą z kart posiadanych w danym kolorze. Kolor zagrywanej karty też często można pominąć (program zagra w jedyny posiadany kolor lub dołoży do koloru).

Zamiast wskazywać kartę do zagrania można wydać następujące komendy:
• u - (undo) cofa ostatnie zagranie
• ut - (undo trick) cofa ostatnią lewę lub do początku bieżącej lewy
• e - (exit) kończy pracę programu

Można też specyfikować kilka instrukcji jednocześnie rozdzielając je spacjami, np. AC x x x może oznaczać nakaz zagrania asa trefl i dołożenia przez pozostałych graczy najmniejszych trefli.

Praca nieinteraktywna (na potrzeby skryptów, itd.)

Program może pracować bez interakcji z użytkownikiem (takie zachowanie pożądane jest np. przy wykorzystaniu programu w różnych skryptach do przeprowadzenia większej ilości analiz). Wystarczy uruchomić go z odpowiednimi opcjami, np.:

bcalconsole -e e -t <atu> -l <wistujący> -q -d <format> -c <rozkład>

Znacznie użytych przełączników:
• -e e - kończy interakcje zaraz po rozpoczęciu, -e wykonuje podane komendy (np. zagrania) zaraz po starcie programu, w tym przypadku podano jedynie komendę zakończenia programu (e), ale ogólnie, można podać większą liczbę poleceń rozdzielając je spacjami (trzeba wtedy umieścić całość w cudzysłowach), np. by dokonać obliczeń po wiście w asa kier i wyjść: -e "AH e";
• -t <atu> - wskazuje kolor atutowy, np. -t s oznacza piki, zaś -t a spowoduje wykonanie obliczeń dla wszystkich kolorów atu;
• -l <wistujący> - wskazuje rękę wistu, np. -l N;
• -q - (opcjonalne) włącza tryb cichy w którym program wypisuje mniej informacji czyniąc swoje wyjście łatwiejszym do przetwarzania;
• -d <format> - specyfikuje format w jakim podano rozkładu kart, np. -b PBN;
• -c <rozkład> - specyfikuje rozkład kart sformatowany zgodnie z przełącznikiem -d, np. -c "S:T74.73.KQ87.7654 QJ53.AKT542..KQ3 8.Q96.AJT32.AJ92" (pominięcie ostatniej ręki dopuszczalne jest tylko wtedy, gdy program może ją wyliczyć, tzn. gdy w pozostałych rękach jest po 13 kart).

By uzyskać więcej informacji i wyświetlić opis wszystkich możliwych parametrów wywołania wystarczy skorzystać z przełącznika --help:

bcalconsole --help

Wklejanie rozdań z wydruków programu KoPS

Uruchamiając program z odpowiednimi parametrami zysukjemy możliwość łatwego wklejenia do niego (ze schowka systemowego) rozkładów rozdań pochodzących z pliku wygenerowanego programem KoPS. Jeśli rozdanie które chcemy przeanalizować pochodzi ze strony html wygenerowanej KoPSem powinniśmy uruchomić program Bridge Calculator za pomocą kops_web.bat, jeśli zaś z pliku tekstowego to za pomocą kops_txt.bat

Na wydruku z KoPSa należy zaznaczyć rozkład interesującego nas rozdania i je skopiować (zwykle za pomocą menu Edycja > Kopiuj lub skrótu klawiszowego ctrl+c). Następnie wkleić rozkład w okno z programem (pod Windows można to zrobić klikając na ikonkę znajdującą się w lewym górnym rogu okna i z wyświetlonego menu wybrać Edytuj > Wklej). Po udanej operacji program zapyta nas o kolor atutowy, itd.

Najczęściej zadawane pytania

Dlaczego w przypadku niektórych rozdań obliczenia trwają bardzo długo?

Problem długiego czasu obliczeń dotyczy rozdań w których bardzo często, we wczesnych fazach gry, gracze muszą dokładać nie do koloru (głównie są to rozdania w których wszyscy gracze posiadają 3 kolorowe ręce - każdy ma renons w innym kolorze). W takich rozdaniach gracz ma przeciętnie do wyboru znacznie więcej zagrań (często dokłada nie do koloru i wybiera np. 1 z 13 kart, zamiast 1 z 3). Złożoność problemu rośnie wykładniczo (kolejne wielkości decyzji przemnażają się przez siebie) i ostatecznie w przypadku tatkich rozdań jest znacznie (miliardy razy!) większy niż w przypadku rozdań "bardziej statystycznych".

W efekcie znacznie rośnie czas obliczeń i potrzebna do nich ilość pamięci operacyjnej. W skrajnych przypadkach ilość pamięci w komputerze może okazać się nie wystarczająca, co może doprowadzić nawet do błędów wykonania programu.

Szczęśliwie problematyczne rozkłady są mało prawdopodobne, praktycznie nie możliwe do uzyskania w drodze rozdawania (w tym "rozdawania" przy użyciu komputera).